diff --git a/.gitignore b/.gitignore index f7d80fcad2245efca25bd67e08596a1ced4781bc..e57c5b8c6b1cda1e2636869d3ed141b6aa119667 100644 --- a/.gitignore +++ b/.gitignore @@ -24,6 +24,7 @@ Testing *.out *.tdo *.toc +*.synctex.gz # always consider files containing source code regardless of their name !*.cc diff --git a/CHANGELOG.md b/CHANGELOG.md index 3ada79a044f6da40509a1ab846da8ebd2ea7b609..b025930f8701337b12f96ac07e61b34e22826f5d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,201 @@ +Differences Between DuMuX 3.1 and DuMuX 3.0 +============================================= + +### Important Notes + +### Improvements and Enhancements + +- Added new porous medium model for the energy balance of a porous solid (general heat equation) +- __Multidomain__: It is now possible to use the facet coupling module together with the mpfa-o scheme in the bulk domain. +- Added a `StaggeredNewtonConvergenceWriter` for the staggered grid discretization scheme +- The box scheme works now on grids with prism / wedge elements in 3D +- The GridManager now support reading unstructured grids and data from vtu/vtp files (ASCII, XML format) sequential + This means for UGGrid and FoamGrid you can now specify a grid in such a format in the input file + `Grid.File = mygrid.vtu` / `Grid.File = mygrid.vtp` and the associated data is available in the grid data object +- __Freeflow__: A second order approximation of the convective term of all navier-stokes based models is now available. + This can be enabled using the property UpwindSchemeOrder. This property defaults to a first order upwinding approximation, + 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. + 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 + uniform grid is used, but two other methods, `Li` and `Hou`, are both available for adaptations to non-uniform grids. + These can be specified using the input file entry `Flux.TVDApproach`. +- __RANS__: The called RANS model, defined in the properties system, will specify, via the model traits, + 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. +- __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. +- __ShallowWater__ The are now some friction laws computing shear stresses (Manning, Nikuradse) to account for friction in a channel/river bed thanks to Martin Utz +- __GridManager__ Instead of always including all gridmanager 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. +- __Solver__ There is a new abstract base class PDESolver that is a class that does linearize & assemble, solve, update. + The NewtonSolver now derives from this class (interface is unchanged). A new class LinearPDESolver simplifies solving linear problems + by reducing the code in the main file and streamlining the terminal output to look like the Newton output. + - 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. + +### Immediate interface changes not allowing/requiring a deprecation period + +- `NewtonConvergenceWriter`'s first template argument has changed from `GridView`, the `FVGridGeometry`. This allows to call the `resize()` method after a grid change without any arguments. + Here is an example of how to instatiate the convergence writer: + ``` + using NewtonConvergenceWriter = Dumux::NewtonConvergenceWriter; + auto convergenceWriter = std::make_shared(*fvGridGeometry); + ``` +- The interface of the abstract `TimeLoopBase` class has been extended by `virtual void advanceTimeStep()`, `virtual void setTimeStepSize(Scalar dt)`, + `virtual Scalar maxTimeStepSize()`, and `virtual bool finished()`, thus forcing the inheriting classes to implement those functions. + `TimeLoop` is no longer a template argument in `NewtonSolver`'s `solve()` method, thereby increasing + type safety and providing better compiler error messages. + +### Deprecated classes/files, to be removed after 3.1: + +### Deprecated member functions, to be removed after 3.1: + +- The convergence writer is no longer passed to `NewtonSolver`'s `solve()` method. + For outputting convergence data, please use `newtonSolver.attachConvergenceWriter(convWriter)` in `main.cc` (directly after instantiating the writer). + To stop the output, the writer can also be detached again using `newtonSolver.detachConvergenceWriter()`. + +### Deleted classes/files, property names, constants/enums + + +Differences Between DuMuX 2.12 and DuMuX 3.0 +============================================= + +## Important Notes + +- DuMuX 3.0 is a major version update. It is not backward compatible in all aspects to 2.12. + The following minor version updates will be, as before for the DuMuX 2-series, always backward compatible + to at least the last minor version update. + +- The tutorial has been replaced by the new module `dumux-course` which is + accessible at https://git.iws.uni-stuttgart.de/dumux-repositories/dumux-course. + We recommend new users and also users experienced with DuMuX 2.X to clone + the course and have a look at the exercises in there. + +- DuMuX 3.0 is based on Dune 2.6 and is expected to run with the current Dune master. + We will try to keep the compatibility with the Dune master + as long as it is technically feasible and our resources allow it. + +- DuMuX 3.0 requires at least GCC 4.9 or Clang 3.5 in their C++-14 mode. + However, we suggest to use newer compiler versions, as we cannot test against all previous compiler versions. + +- For employing corner-point grids by means of opm-grid, the OPM release 2018.10 has to be used. + +## Improvements and Enhancements + +### General + +- __New style main files:__ 3.0 comes which a major overhaul of how the sequence of simulation steps is specified. + Until 2.12 there was the start.hh header including the free function `start` that contained a predefined sequence of + steps. Customization of the sequence was possible by many hooks implemented in classes used in this sequence. This + made it hard to follow the course of the program and hard to implement customization at points where this was not previously envisioned. + In contrast, in the new approach the sequence of simulation steps was linearized, meaning that each step is visible + in the program's main file. In the new main files, one can clearly see the io, initialization, assembly, solving, update, time loop, etc., + of the program. Many parts of the simulation that were previously mandatory, i.e. simulations in 2.12 always contained a time loop, + are now optional (stationary simulations just don't need a time loop). The new style main files make it easier two follow the course + of the program, are easier to customize, and offer more flexibility concerning the customization of steps and components of a simulation. + All tests and examples in the dumux repository have been adapted to the new style main files. +- __Property system:__ The property system is now usable without preprocessor macros. To this end it was completely reimplemented using C++14 techniques and + variadic templates. The hierarchies can now be arbitrarily deep instead of being limited to 5 levels. The new implementation does not use + C++ inheritance. Properties and TypeTag now have to be properly qualified with the namespaces `Properties::`, `TTag::`. Types that share the + name with properties have to properly qualified with the `Dumux::` namespace. This update makes it hopefully more readable + and removes the "magic" part from the property system. +- __Runtime parameters:__ Runtime parameters are no longer accessed with preprocessor macros. They have been replaced by C++ function templates + `Dumux::getParam`, `Dumux::hasParam`, `Dumux::getParamFromGroup`. The `..FromGroup` version has been redesigned to allow the specification + of parameters for different models in one input file. The concept of a parameter group string was extended to make it possible to + use a single input file for complex multidomain simulation setups. +- __Restarting simulations:__ The old restart module was replaced by an implementation based on a VTK backend (other formats might be added later such as HDF5). + Restarted simulations can read solutions from vtk files. For parallel runs, there is currently the restriction that the number of processors has to be the same + as before the restart. Restarted simulations can read grids from vtk (currently only sequential, non-adaptive grids, support for parallel and adaptive + will be added in a future version). +- __Assembly__: The assembler can now assemble implicit and explicit Euler time discretizations. An interface for implementing analytical Jacobians was added. + The CCTpfa assembler has been significantly improved for complex models that spend a lot of time computing constitutive laws. Also the numerical + differentiation scheme was improved by altering the order in which derivatives are computed. +- __TypeTag templates:__ Implementers of code in DuMuX 3.0 are advised to avoid TypeTag as a template argument for class templates. + Many classes in the DuMuX core have been changed to have a small number of specific template arguments, including `GridGeometry`, + `TimeLoop`, `Newton`, `LinearSolver`, `SpatialParams`. This makes it possible to share objects of these types between models using + different TypeTags. This was not possible before as `Class` and `Class` are different types, even if they contain + exactly the same implementation code. + Furthermore, having TypeTag as a template argument leads to bad programming, and unnecessary dependencies that should be avoided in + every object-oriented code. +- __The grid geometry concept:__ In version 3.0, discretization methods use grid geometries which are wrappers or adapters around a `Dune::GridView`, + providing data structures and interfaces necessary to implement these discretization methods easily. In particular, the + abstraction of sub-control-volumes (scv) and sub-control-volume-faces (scvf) are now separate classes and the grid geometry provides means to iterate + over all scvs and scvfs of an element, using range-based-for loops. +- __The caching concept:__ Version 3.0 introduces a caching concept for the new grid geometry, the volume variables and the flux variables. + There are classes with a `Grid` prefix, that store data for the current grid view, and classes with the `Element` prefix that store data locally + for an element or element stencil. Depending on the caching concept used, data will be either stored completely in the `Grid` objects + (e.g. `GridGeometry`) and the `Element` objects (e.g. `ElementGeometry`) are mere accessor objects, or, data will be partly only cached locally. + Local caching uses less memory but might result in an increased runtime. Grid caching is memory intensive + but can provide a significant run-time speedup. Choose whatever concept fits your available resources, + the default being local caching. +- __Support__ for grid managers `dune-subgrid` (a meta grid selecting only certain elements from a host grid) + and `dune-spgrid` (a structured parallel grid manager, supporting periodic boundaries). + +### Models, Physics and Methods + +- __MPFA schemes:__ The new design of the DuMuX core facilitates the incorporation of new finite-volume schemes. In particular, the new core comes with + a framework for MPFA schemes, in which currently the only available scheme is the MPFA-O scheme. It can be used in conjunction with any DuMuX model and + also works on surface grids. More schemes will be added in the future. +- __Box-dfm:__ The `2pdfm` model from version 2.12 has been generalized such that it can be used on any DuMuX model and in both two and three dimensions. +- __Tracer transport__: A new model for tracer transport with a given flow field has been added. The model can be also used to implement sequentially + coupled simulations, or iterative solvers where flow and transport are decoupled / weakly coupled. +- __Mineralization__: An adapter model for mineralization has been added and can be used with all porousmediumflow models. A balance for the solid + volume fraction of precipitating, adsorbed, or absorbed substances is added to the existing equations. +- __Solution-dependent spatial params:__ A redesign of the spatial params interface allows now to define spatial parameters such as permeability + and porosity that depend on the solution. This makes it easier to implement mineralization models altering the solid structure of the porous medium. +- __Solid systems:__ DuMuX 3.0 introduces solid systems similar to fluid systems but for solid components. This allows a consistent + implementation of mineralization models including reactions, dissolution, precipitation and other processes altering the solid + phase of the porous medium. +- __Multidomain:__ DuMuX 3.0 introduces a new multidomain framework which does no longer depend on `dune-multidomain` and can be used for the coupling + of an arbitrary number of subdomains. The sub-domains can be regions in which different sets of equations are solved and/or which have different + dimensionalities. The implementation is such that any of the existing DuMuX models can be used in the subdomains, while the data and functionality + required for the coupling of the sub-domains is implemented in a `CouplingManger` class. Three different coupling concepts are available, for which + there are a number of available `CouplingManager` class implementations: + - _Boundary:_ coupling across sub-domain boundaries + - _Embedded:_ Coupling between a bulk domain and an embedded lower-dimensional sub-domain which has an independent grid + - _Facet:_ Coupling betweeen a bulk domain and a codimension-one sub-domain, which is conforming with the element facets of the bulk domain +- __Free-flow models:__ The previous Navier-Stokes model using the box method has been replaced by one that employs a staggered grid discretization. + The new method does not require any stabilization techniques while those were necessary for the box method in order to avoid spurious oscillations. + The free-flow models in DuMuX 3.0 consider single phase flow with or without component/energy transport. So far, only regular Cartesian grids are supported + but local grid refinement will be added in a future release. + Several RANS models for turbulent flow have been added: k-omega, k-epsilon, low-Re-k-epsilon, one-eq, zero-eq. The RANS models might be subject to further (interface) + changes. +- __Thermal and chemical non-equilibrium:__ The possibility to consider thermal and/or chemical non-equilibrium of several types has been enabled for all + porous medium models. +- __Interface solver:__ For the two-phase flow model in conjunction with the box scheme, an interface solver can now be used to reconstruct the saturations + in the sub-control volumes adjacent to vertices that lie on material discontinuities. This allows a sharper representation of the saturation front evolving + in heterogeneous porous media. +- __Components:__ Components can now derive from different base classes, `Base`, `Liquid`, `Solid`, `Gas`, depending on which + phase states are implemented. This can be used to determine at compile time if a component supports a certain phase state. +- __Tabulation of fluid parameter laws:__ The tabulation of fluid parameter laws has been improved to only tabulate those functions actually used during the + simulation. To this end, the tabulation is done on the first call of a corresponding fluid parameter. +- __MPNC:__ The general m-phase n-component model has been adapted in structure to the other porous medium flow models. +- __Different wettability:__ The 2p models can now model materials with different wettability (hydrophobic, hydrophilic) in different parts of the domain. +- __Maxwell-Stefan-diffusion:__ Most models can now use Maxwell-Stefan diffusion for multi-component diffusion instead of Fickian diffusion. + There are also a few tests demonstrating how to use it. + +## Immediate interface changes not allowing/requiring a deprecation period + +- Many classes have been completely redesigned. See the numerous example applications included in 3.0 showcasing all new classes. +- The `GridCreator` has been replaced by the `GridManager`, which no longer uses a singleton for the grid object. + This makes it possible to create two grids of the exact same type. The `GridManager` also handles user data provided in grid files. + +## 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. + +## Deleted classes/files/functions... which have been deprecated in DuMuX 2.12 +- Everything listed as deprecated below has been removed. + + Differences Between DuMuX 2.11 and DuMuX 2.12 ============================================= @@ -10,7 +208,7 @@ Differences Between DuMuX 2.11 and DuMuX 2.12 [test/multidomain/README](test/multidomain/README) for details. Also the geomechanics models require Dune 2.4 and PDELab 2.0. - - DuMux 2.12 requires at least GCC 4.9 or Clang 3.5 in their C++-14 mode. + - DuMuX 2.12 requires at least GCC 4.9 or Clang 3.5 in their C++-14 mode. - For employing corner-point grids by means of opm-grid (former dune-cornerpoint), the OPM releases 2017.04 or 2017.10 have to be used. @@ -59,7 +257,7 @@ Differences Between DuMuX 2.10 and DuMuX 2.11 Dune 2.4 core and specific versions of other modules, see `test/multidomain/README` for details. - - DuMux 2.11 requires at least GCC 4.9 or Clang 3.5 in their C++-14 mode. + - DuMuX 2.11 requires at least GCC 4.9 or Clang 3.5 in their C++-14 mode. - For employing corner-point grids by means of opm-grid (former dune-cornerpoint), the OPM release 2016.04 has to be used. @@ -110,7 +308,7 @@ Differences Between DuMuX 2.9 and DuMuX 2.10 Dune 2.4 core and specific versions of other modules, see `test/multidomain/README` for details. - - DuMux 2.10 requires at least GCC 4.9 or Clang 3.5 in their C++-14 mode. + - DuMuX 2.10 requires at least GCC 4.9 or Clang 3.5 in their C++-14 mode. - For employing corner-point grids by means of opm-grid (former dune-cornerpoint), the OPM release 2016.04 has to be used. @@ -129,8 +327,8 @@ Differences Between DuMuX 2.9 and DuMuX 2.10 - Using the geostatistical tool gstat for generating random fields has been facilitated. See `test_cc1pwithgstat` in `test/porousmediumflow/1p/implicit`. This tool can be installed using the `bin/installexternal.sh` script. - If cmake does not find gstat, one has to specify the GSTAT_ROOT variable, - see the standard optim.opts or debug.opts. + If cmake does not find gstat, one has to specify the GSTAT_ROOT variable, + see the standard optim.opts or debug.opts. - The multidomain models should now run with all compilers without segfaults, both with optimization and debug options. @@ -246,7 +444,7 @@ Differences Between DuMuX 2.8 and DuMuX 2.9 ``` find . -name '*.[ch][ch]' -exec bash ../dumux/bin/fix_includes.sh {} \; ``` - inside the folder that contains your files. + inside the folder that contains your files. A patch is available to remove deprecated header files: ``` patch -p1 < patches/dumux-2.9-no-deprecated-headers.patch @@ -270,7 +468,7 @@ Differences Between DuMuX 2.8 and DuMuX 2.9 ``` with the new ``` - #include + #include ``` The structure change is reflected in the `test` folder: + The tests from`test/implicit/particular_model` have been moved to @@ -324,7 +522,7 @@ Differences Between DuMuX 2.8 and DuMuX 2.9 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 - + inherit from flux variables from dumux-stable, such as the + + inherit from flux variables from dumux-stable, such as the `ImplicitDaryFluxVariables`, + and/or are used in a local residual from dumux-stable. See the @@ -642,7 +840,7 @@ Differences Between DuMuX 2.6 and DuMuX 2.7 classes FVSpatialParamsOneP and ImplicitSpatialParamsOneP. * Deprecated protected MEMBER VARIABLES, to be removed after 2.7: BEWARE: Older - compilers will not print any warning if a deprecated protected member variable + compilers will not print any warning if a deprecated protected member variable is used. - In dumux/nonlinear/newtoncontroller.hh: "error_" -> "shift_" @@ -743,7 +941,7 @@ Differences Between DuMuX 2.5 and DuMuX 2.6 have been deprecated: subProblemX, subModelX, subIDX, gridViewX with X=1,2. They are replaced by sdProblemX, sdModelX, sdIDX, sdGridViewX. -* DELETED classes/files, property names, constants/enums, +* DELETED classes/files, property names, constants/enums, member functions, which have been deprecated in DuMuX 2.5: Everything listed as deprecated below has been removed. @@ -756,11 +954,11 @@ Differences Between DuMuX 2.4 and DuMuX 2.5 available for the decoupled compositional 2p2c models. It also allows for simulation on an adaptive grid. - Coupling of 2c2p with stokesnc and 2p2cNI with Stokesncni was - added. The stokes2c and stokes2cni are now DEPRECATED and will be kicked - out by the next release. Instead generalized stokesnc and stokesncni - models are introduced. Unlike 2c models the transport equations in + added. The stokes2c and stokes2cni are now DEPRECATED and will be kicked + out by the next release. Instead generalized stokesnc and stokesncni + models are introduced. Unlike 2c models the transport equations in the nc models are capapable of using both mass and mole fractions. - NOTE: For coupling test examples be aware of the harsh version + NOTE: For coupling test examples be aware of the harsh version restrictions mentioned in dumux/test/modelcoupling/README. * IMMEDIATE INTERFACE CHANGES not allowing/requiring a deprecation period: @@ -770,7 +968,7 @@ Differences Between DuMuX 2.4 and DuMuX 2.5 - Stokes2cModel was replaced by StokesNCModel, similar for more Stokes2c* classes. -* DELETED classes/files, property names, constants/enums, +* DELETED classes/files, property names, constants/enums, member functions, which have been deprecated in DuMuX 2.4: Everything listed as deprecated below has been removed. @@ -785,8 +983,8 @@ Differences Between DuMuX 2.3 and DuMuX 2.4 error is thrown during compilation if the flag is not set. For reference see the commented part in optim.opts and debug.opts. - - All two-component models (1p2c, 2p2c, 2p2cni, co2, co2ni) can now be used - with either mole or mass fractions. The property useMoles has to be set in + - All two-component models (1p2c, 2p2c, 2p2cni, co2, co2ni) can now be used + with either mole or mass fractions. The property useMoles has to be set in the problem file and the boundary conditions have to be choosen accordingly. . 1p2c, 2p2c, 2p2cni use MOLE fractions by default. . co2, co2ni use MASS fractions by default. @@ -830,7 +1028,7 @@ Differences Between DuMuX 2.3 and DuMuX 2.4 - All fully-implicit porous-media models now provide the possibility to write the velocities to the VTK output. This can be achieved by setting the - parameter "AddVelocity" of the group "Vtk" or the corresponding property + parameter "AddVelocity" of the group "Vtk" or the corresponding property "VtkAddVelocity." See test/implicit/1p2c for an example. - The CMake build system support uses the experimental mechanisms from DUNE. @@ -845,7 +1043,7 @@ Differences Between DuMuX 2.3 and DuMuX 2.4 have been replaced by more generic ones. See the deprecation listings below or FS#194 for details. - - The ...FVElementGeometry classes have been cleaned up a bit. See the + - The ...FVElementGeometry classes have been cleaned up a bit. See the deprecation listings below or FS#192 for details. - Added compiler support for Clang 3.2, Clang 3.3, and GCC 4.8. @@ -854,23 +1052,23 @@ Differences Between DuMuX 2.3 and DuMuX 2.4 - OnePBoxModel, OnePTwoCBoxModel -> OnePModel, OnePTwoCModel - Headers containing capitalized letters are replaced by their non-capitalized - analogs. - In dumux/decoupled: 1p/cellData1p.hh, 1p/fluxData1p.hh, + analogs. + In dumux/decoupled: 1p/cellData1p.hh, 1p/fluxData1p.hh, 2p/cellData2padaptive.hh, 2p/fluxData2p.hh, 2p/cellData2p.hh, 2p2c/cellData2p2c.hh, 2p2c/cellData2p2cadaptive.hh, 2p2c/fluxData2p2c.hh, 2p2c/cellData2p2cmultiphysics.hh. In dumux/material/fluidmatrixinteractions/3p: parkerVanGen3p.hh, parkerVanGen3pparams.hh. -* Deprecated CONSTANTS/ENUMS, to be removed after 2.4: BEWARE: Older compilers +* Deprecated CONSTANTS/ENUMS, to be removed after 2.4: BEWARE: Older compilers will not print any warning if a deprecated constant/enum is used. - - saturation indices: S0Idx, SnIdx, SnOrXIdx, SOrX1Idx, SOrX2Idx, SwIdx, + - saturation indices: S0Idx, SnIdx, SnOrXIdx, SOrX1Idx, SOrX2Idx, SwIdx, SwOrXIdx -> s0Idx, snIdx, snOrXIdx, sOrX1Idx, sOrX2Idx, swIdx, swOrXIdx - two-phase formulations: pnSn, pnSw, pwSn, pwSw -> pnsn, pnsw, pwsn, pwsw - - DecoupledTwoPCommonIndices: pressureNW, saturationNW, velocityNW + - DecoupledTwoPCommonIndices: pressureNW, saturationNW, velocityNW -> pressureNw, saturationNw, velocityNw - DecoupledTwoPIndices: pressEqIdx -> pressureEqIdx @@ -879,7 +1077,7 @@ Differences Between DuMuX 2.3 and DuMuX 2.4 -> numPrimaryEnergyVars, numPrimaryVars * Deprecated public MEMBER VARIABLES, to be removed after 2.4: BEWARE: Older - compilers will not print any warning if a deprecated public member variable + compilers will not print any warning if a deprecated public member variable is used. - ...FVElementGeometry: numEdges, numFaces, numFap, numVertices -> numScvf, -, numFap of each subcontrolvolume face, numScv @@ -896,33 +1094,33 @@ Differences Between DuMuX 2.3 and DuMuX 2.4 - ImplicitProblem: boxSDNeumann(), boxSDSource() -> solDependentNeumann(), solDependentSource() - - ImplicitPorousMediaProblem: boxGravity(), boxTemperature() + - ImplicitPorousMediaProblem: boxGravity(), boxTemperature() -> gravityAtPos(), temperatureAtPos() (different signatures!) - - fluid-matrix-interactions: dkrn_dSw(), dkrw_dSw(), dpc_dSw(), pC(), + - fluid-matrix-interactions: dkrn_dSw(), dkrw_dSw(), dpc_dSw(), pC(), dSw_dpC(), Sgr(), Snr(), SnToSne(), Sw(), Swr(), SwToSwe() - -> dkrn_dsw(), dkrw_dsw(), dpc_dsw(), pc(), dsw_dpc(), sgr(), snr(), + -> dkrn_dsw(), dkrw_dsw(), dpc_dsw(), pc(), dsw_dpc(), sgr(), snr(), snToSne(), sw(), swr(), swToSwe() - - LinearMaterial(Params): entryPC(), maxPC(), setEntryPC(), setMaxPC() + - LinearMaterial(Params): entryPC(), maxPC(), setEntryPC(), setMaxPC() -> entryPc(), maxPc(), setEntryPc(), setMaxPc() - - RegularizedVanGenuchten(Params): pCHighSw(), pCLowSw() + - RegularizedVanGenuchten(Params): pCHighSw(), pCLowSw() -> pcHighSw(), pcLowSw() - VanGenuchtenParams, ParkerVanGen3PParams: setVgM(), setVgN(), vgM(), vgN() -> setVgm(), setVgn(), vgm(), vgn() - - ParkerVanGen3P(Params): betaGN(), betaGW(), betaNW(), pCAlpha(), pCGN(), + - ParkerVanGen3P(Params): betaGN(), betaGW(), betaNW(), pCAlpha(), pCGN(), pCGW(), pCNW(), setBeta..., setkrRegardsSnr(), Swrx() - -> betaGn(), betaGw(), betaNw(), pcAlpha(), pcgn(), pcgw(), pcnw(), + -> betaGn(), betaGw(), betaNw(), pcAlpha(), pcgn(), pcgw(), pcnw(), setBeta..., setKrRegardsSnr(), swrx() - MPLinearMaterialParams: Sreg() -> sReg() - EvalCflFlux...: getCFLFluxFunction() -> getCflFluxFunction - - FVMPFAOInteractionVolume: getNTKNu_by_dF(), getNTKNu(), getNTKrKNu_by_dF(), + - FVMPFAOInteractionVolume: getNTKNu_by_dF(), getNTKNu(), getNTKrKNu_by_dF(), getNTKrKNu() -> getNtkNu_df(), getNtkNu(), getNtkrkNu_df(), getNtkrkNu() @@ -930,12 +1128,12 @@ Differences Between DuMuX 2.3 and DuMuX 2.4 - Stokes...Variables: viscosity() -> dynamicViscosity() - - IAPWS water: ddgamma_ddpi, ddgamma_ddtau, ddgamma_dtaudpi, dgamma_dpi, - dgamma_dtau, dp_dpi, dpi_dp, dtau_dt - -> ddGamma_ddPi, ddGamma_ddTau, ddGamma_dTaudPi, dGamma_dPi, dGamma_dTau, + - IAPWS water: ddgamma_ddpi, ddgamma_ddtau, ddgamma_dtaudpi, dgamma_dpi, + dgamma_dtau, dp_dpi, dpi_dp, dtau_dt + -> ddGamma_ddPi, ddGamma_ddTau, ddGamma_dTaudPi, dGamma_dPi, dGamma_dTau, dp_dPi, dPi_dp, dTau_dt -* DELETED classes/files, property names, constants/enums, +* DELETED classes/files, property names, constants/enums, member functions/variables, which have been deprecated in DuMuX 2.3: Everything listed as deprecated below has been removed. @@ -944,7 +1142,7 @@ Differences Between DuMuX 2.2 and DuMuX 2.3 =================================================== * IMPROVEMENTS and ENHANCEMENTS: - - A fully implicit two-phase discrete-fracture-matrix model has been added, + - A fully implicit two-phase discrete-fracture-matrix model has been added, see test/implicit/2pdfm. - Almost all porous media fully implicit models now can either use a @@ -952,10 +1150,10 @@ Differences Between DuMuX 2.2 and DuMuX 2.3 of the spatial discretization method is controlled by deriving the problem type tag either from BoxModel or CCModel. This allows for a uniform problem description, as long as the boundaryTypesAtPos and dirichletAtPos methods - can be used. By evaluating the compile-time property ImplicitIsBox, it is - easily possible to separately handle the different discretizations inside - am common method. See the tests in test/implicit for examples. - Correspondingly, the directory structure has been adapted. + can be used. By evaluating the compile-time property ImplicitIsBox, it is + easily possible to separately handle the different discretizations inside + am common method. See the tests in test/implicit for examples. + Correspondingly, the directory structure has been adapted. Old: New: dumux/ dumux/ boxmodels/ implicit/ @@ -972,71 +1170,71 @@ Differences Between DuMuX 2.2 and DuMuX 2.3 ... - A backend for the ISTL AMG solver has been included, based on the - corresponding DUNE-PDELab backends. It can be used for the fully - implicit and the decoupled models, see test_*1pwithamg in - test/implicit/1p and test_impeswithamg in test/decoupled/2p. - DUNE-PDELab and possibly DUNE-ISTL have to be patched, see the file - README in the patches directory. + corresponding DUNE-PDELab backends. It can be used for the fully + implicit and the decoupled models, see test_*1pwithamg in + test/implicit/1p and test_impeswithamg in test/decoupled/2p. + DUNE-PDELab and possibly DUNE-ISTL have to be patched, see the file + README in the patches directory. - - The decoupled models have been parallelized, see test_impeswithamg in - test/decoupled/2p. They work in parallel only if the AMGBackend is used - as linear solver. No dynamic loadbalancing can be done yet. + - The decoupled models have been parallelized, see test_impeswithamg in + test/decoupled/2p. They work in parallel only if the AMGBackend is used + as linear solver. No dynamic loadbalancing can be done yet. - The MPNC model can use either the most wetting or the most non-wetting phase - pressure as primary variable. This is controlled via the property + pressure as primary variable. This is controlled via the property "PressureFormulation." - - The table of available parameters has been improved, see + - The table of available parameters has been improved, see http://www.dumux.org/doxygen-stable/html-2.2/a00838.php - - Improved handling of the conductive heat fluxes in the non-isothermal implicit + - Improved handling of the conductive heat fluxes in the non-isothermal implicit two-phase models, see the problem files in test/implicit/2p(2c)ni. - Introduced new selection of start/stop messages. * IMMEDIATE INTERFACE CHANGES not allowing/requiring a deprecation period: - - The property Salinity used in the BrineCO2FluidSystem - has been renamed to ProblemSalinity. + - The property Salinity used in the BrineCO2FluidSystem + has been renamed to ProblemSalinity. - The matrixHeatFlux(...) and boundaryMatrixHeatFlux(...) methods in the spatial parameters of nonisothermal implicit twophase models have been removed. - Instead, the computation of the effective thermal conductivity has been sourced - out to the fluidmatrixinteractions in a separate file + Instead, the computation of the effective thermal conductivity has been sourced + out to the fluidmatrixinteractions in a separate file dumux/material/fluidmatrixinteractions/thermalconductivitysomerton.hh, which - can be exchanged. The spatial parameters file needs a method + can be exchanged. The spatial parameters file needs a method thermalConductivitySolid(...), where the thermal conductivity of the solid material only is specified. The rest is computed in the respective flux variables. * Deprecated CLASSES/FILES, to be removed after 2.3: - - The following headers in dumux/boxmodels/ have been deprecated and forward - to the corresponding headers in dumux/implicit/box: + - The following headers in dumux/boxmodels/ have been deprecated and forward + to the corresponding headers in dumux/implicit/box: boxassembler.hh, boxelementvolumevariables.hh, boxlocalresidual.hh, boxpropertydefaults.hh, boxelementboundarytypes.hh, boxfvelementgeometry.hh, boxproperties.hh, intersectiontovertexbc.hh - - All headers in the following subdirectories of dumux/boxmodels have been - deprecated and forward to the headers in the corresponding subdirectories + - All headers in the following subdirectories of dumux/boxmodels have been + deprecated and forward to the headers in the corresponding subdirectories of dumux/implicit: - 1p, 1p2c, 2p, 2p2c, 2p2cni, 2pdfm, 2pni, + 1p, 1p2c, 2p, 2p2c, 2p2cni, 2pdfm, 2pni, 3p3c, 3p3cni, co2, co2ni, mpnc, richards - - Some box-specific classes "Box..." in dumux/boxmodels/common could be - completely replaced by unified "Implicit..." classes in - dumux/implicit/common: - ...DarcyFluxVariables, ...darcyfluxvariables.hh - ...ForchheimerFluxVariables, ...forchheimerfluxvariables.hh + - Some box-specific classes "Box..." in dumux/boxmodels/common could be + completely replaced by unified "Implicit..." classes in + dumux/implicit/common: + ...DarcyFluxVariables, ...darcyfluxvariables.hh + ...ForchheimerFluxVariables, ...forchheimerfluxvariables.hh ...LocalJacobian, ...localjacobian.hh ...Model, ...model.hh ...PorousMediaProblem, ...porousmediaproblem.hh ...Problem, ...problem.hh ...VolumeVariables, ...volumevariables.hh - - The box-specific spatial parameter classes BoxSpatialParams... in - dumux/material/boxspatialparams....hh have been deprecated in favor of + - The box-specific spatial parameter classes BoxSpatialParams... in + dumux/material/boxspatialparams....hh have been deprecated in favor of ImplicitSpatialParams... in dumux/material/implicitspatialparams....hh. - - The GridCreatorheaders from dumux/common have been moved to dumux/io: + - The GridCreatorheaders from dumux/common have been moved to dumux/io: cubegridcreator.hh, dgfgridcreator.hh, simplexgridcreator.hh * Deprecated PROPERTY NAMES, to be removed after 2.3: BEWARE: The compiler will @@ -1044,19 +1242,19 @@ Differences Between DuMuX 2.2 and DuMuX 2.3 - CompositionFromFugacitiesSolver has been renamed to Constraintsolver. * Deprecated public MEMBER VARIABLES, to be removed after 2.3: BEWARE: The - compiler will not print any warning if a deprecated public member variable + compiler will not print any warning if a deprecated public member variable is used. - - numFAP and numSCV in Box(CC)FVElementGeometry have been renamed to + - numFAP and numSCV in Box(CC)FVElementGeometry have been renamed to numFap and numScv, respectively. * Deprecated MEMBER FUNCTIONS, to be removed after 2.3: - - boundaryMatrixHeatFlux, markVertexRed and relativeErrorVertex - from ImplicitSpatialParams, ImplicitAssembler and ImplicitModel, - respectively. In favor of using - thermalConductivitySolid (see above), markDofRed and relativeErrorDof, - respectively. + - boundaryMatrixHeatFlux, markVertexRed and relativeErrorVertex + from ImplicitSpatialParams, ImplicitAssembler and ImplicitModel, + respectively. In favor of using + thermalConductivitySolid (see above), markDofRed and relativeErrorDof, + respectively. -* DELETED classes/files, property names, constants/enums, +* DELETED classes/files, property names, constants/enums, member functions, which have been deprecated in DuMuX 2.2: Everything listed as deprecated below has been removed. @@ -1064,41 +1262,41 @@ Differences Between DuMuX 2.2 and DuMuX 2.3 Differences Between DuMuX 2.1 and DuMuX 2.2 =================================================== -* IMPROVEMENTS and ENHANCEMENTS: +* IMPROVEMENTS and ENHANCEMENTS: - Two new fully implicit models dedicated to simulate compositional - (non-isothermal) CO2-brine systems have been added, together with - corresponding components and a fluid system. See test/boxmodels/co2(ni) - for details. These tests also illustrate the usage of element and vertex - parameters as well as boundary ids provided by DGF files for setting + (non-isothermal) CO2-brine systems have been added, together with + corresponding components and a fluid system. See test/boxmodels/co2(ni) + for details. These tests also illustrate the usage of element and vertex + parameters as well as boundary ids provided by DGF files for setting permeability and porosity as well as boundary conditions. - Decoupled Models: An h-adaptive model using an MPFA L-method was added - that simulates 2p and 2p2c flow on unstructured grids with hanging nodes + that simulates 2p and 2p2c flow on unstructured grids with hanging nodes in two dimensions. See test/decoupled/2p(2c) for details. - - All fully implicit porous media models are now capable of employing - the Forchheimer equation as an alternative to the commonly used - Darcy law. See test_forchheimer*p in test/boxmodels/mpnc for details. + - All fully implicit porous media models are now capable of employing + the Forchheimer equation as an alternative to the commonly used + Darcy law. See test_forchheimer*p in test/boxmodels/mpnc for details. - - The Stokes models are now able to simulate the full Navier-Stokes - equations for momentum transport. See test/freeflow/navierstokes + - The Stokes models are now able to simulate the full Navier-Stokes + equations for momentum transport. See test/freeflow/navierstokes for details. - - The fully implicit models have been (partially) generalized to allow - for a cell-centered discretization in addition to the default - vertex-centered (box) one. Cell-centered fully implicit 2p and 2p2c - models are already available in the developers part of Dumux. Further - generalizations and the inclusion in the stable part are planned for + - The fully implicit models have been (partially) generalized to allow + for a cell-centered discretization in addition to the default + vertex-centered (box) one. Cell-centered fully implicit 2p and 2p2c + models are already available in the developers part of Dumux. Further + generalizations and the inclusion in the stable part are planned for Dumux 2.3. - - Several model-specific features and classes have been unified, like - the calculation of the Darcy velocity for the fully implicit flux - variables, or the temperature, gravity, and spatial parameter + - Several model-specific features and classes have been unified, like + the calculation of the Darcy velocity for the fully implicit flux + variables, or the temperature, gravity, and spatial parameter functionalities of the fully implicit problems. Moreover, many - names have been made more consistent. This includes the naming - and grouping of several parameters and corresponding properties, - the indexing of phases and components, and the preference of the - partial name "params" over "parameters." For details, see also the + names have been made more consistent. This includes the naming + and grouping of several parameters and corresponding properties, + the indexing of phases and components, and the preference of the + partial name "params" over "parameters." For details, see also the deprecations listed below. - Added compiler support for GCC 4.7 and Clang 3.1. @@ -1107,23 +1305,23 @@ Differences Between DuMuX 2.1 and DuMuX 2.2 - From Dune 2.2 on, FieldVector::size is a method rather than an enum value. It is mandatory to add the flag --enable-fieldvector-size-is-method to the CONFIGURE_FLAGS. An example is given in the opts file dumux/debug.opts. - - Implicit models: TwoPIndices, TwoPNIIndices, and RichardsIndices - additionally get TypeTag as template parameter. If the Indices are not + - Implicit models: TwoPIndices, TwoPNIIndices, and RichardsIndices + additionally get TypeTag as template parameter. If the Indices are not obtained via the property, this has to be adapted. - - Implicit models: All model-specific computeFlux functions in - ...localresidual.hh have to get an additional bool parameter onBoundary, - which is by default set to false. If outflow conditions should - be properly implemented, also the constructor of the flux variables in - ...fluxvariables.hh has to get the additional argument and the + - Implicit models: All model-specific computeFlux functions in + ...localresidual.hh have to get an additional bool parameter onBoundary, + which is by default set to false. If outflow conditions should + be properly implemented, also the constructor of the flux variables in + ...fluxvariables.hh has to get the additional argument and the class has to be adapted to deal with boundary faces. See FS#117 and #99 for details. - + * Deprecated CLASSES/FILES, to be removed after 2.2: - - Model specific base box problems: The common functionality has been - collected in PorousMediaBoxProblem in - dumux/boxmodels/common/porousmediaboxproblem.hh. The problem can be derived - from PorousMediaBoxProblem, instead of the model specific base problem: + - Model specific base box problems: The common functionality has been + collected in PorousMediaBoxProblem in + dumux/boxmodels/common/porousmediaboxproblem.hh. The problem can be derived + from PorousMediaBoxProblem, instead of the model specific base problem: OnePBoxProblem, dumux/boxmodels/1p/1pproblem.hh, OnePTwoCBoxProblem, dumux/boxmodels/1p2c/1p2cproblem.hh, TwoPProblem, dumux/boxmodels/2p/2pproblem.hh, @@ -1133,83 +1331,83 @@ Differences Between DuMuX 2.1 and DuMuX 2.2 ThreePThreeCProblem, dumux/boxmodels/3p3c/3p3cproblem.hh, ThreePThreeCNIProblem, dumux/boxmodels/3p3cni/3p3cniproblem.hh, MPNCProblem, dumux/boxmodels/mpnc/mpncproblem.hh. - - - All "...SpatialParameters" base classes have been replaced by + + - All "...SpatialParameters" base classes have been replaced by "...SpatialParams" classes: BoxSpatialParameters, dumux/material/spatialparameters/boxspatialparameters.hh, BoxSpatialParametersOneP, dumux/material/spatialparameters/boxspatialparameters1p.hh, FVSpatialParameters, dumux/material/spatialparameters/fvspatialparameters.hh, FVSpatialParametersOneP, dumux/material/spatialparameters/fvspatialparameters1p.hh. - - Due to the unification of flux variables for the fully implicit models, - some model-specific flux variables have become obsolete: + - Due to the unification of flux variables for the fully implicit models, + some model-specific flux variables have become obsolete: OnePFluxVariables, dumux/boxmodels/1p/1pfluxvariables.hh, TwoPFluxVariables, dumux/boxmodels/2p/2pfluxvariables.hh, RichardsFluxVariables, dumux/boxmodels/richards/richardsfluxvariables.hh. - - Two components have new names and locations in dumux/material/components: + - Two components have new names and locations in dumux/material/components: SimpleDNAPL, simplednapl.hh -> DNAPL, napl.hh Oil, oil.hh -> LNAPL, lnapl.hh - - Some MPFA-O method files/classes have been moved to a new subdirectory - "omethod" in dumux/decoupled/2p/diffusion/fvmpfa: + - Some MPFA-O method files/classes have been moved to a new subdirectory + "omethod" in dumux/decoupled/2p/diffusion/fvmpfa: fvmpfaopressure2p.hh, fvmpfaovelocity2p.hh, fvmpfaopressureproperties2p.hh - - DUMUX_UNUSED is deprecated and will be removed after 2.2. It should be + - DUMUX_UNUSED is deprecated and will be removed after 2.2. It should be replaced by the upstream version DUNE_UNUSED. - + - DUMUX_DEPRECATED_MSG is deprecated and will be removed after 2.2. It should be replaced by the upstream version DUNE_DEPRECATED_MSG. * Deprecated PROPERTY NAMES, to be removed after 2.2: BEWARE: The compiler will - not print any warning if a deprecated property name is used. + not print any warning if a deprecated property name is used. - The "SpatialParameters" property has been renamed to "SpatialParams". - + - The model specific "...Indices" property has been renamed to "Indices". * Deprecated CONSTANTS/ENUMS, to be removed after 2.2: BEWARE: The compiler will not print any warning if a deprecated constant/enum is used. - - In the 2p2c/ni and 3p3c/ni models, all indices related to phase and - components can be pre/suffixed with "w", "n" and, - for three phases, with "g". + - In the 2p2c/ni and 3p3c/ni models, all indices related to phase and + components can be pre/suffixed with "w", "n" and, + for three phases, with "g". boxmodels/2p2c/...: "l", "g" pre/suffixes have been replaced by "w", "n". boxmodels/3p3c/...: "c", "a" pre/suffixes have been replaced by "n", "g". * Deprecated MEMBER FUNCTIONS, to be removed after 2.2: - - Spatial parameters: The spatialParameters member functions of the base - problems have been replaced by spatialParams: - dumux/boxmodels/common/porousmediaboxproblem.hh, + - Spatial parameters: The spatialParameters member functions of the base + problems have been replaced by spatialParams: + dumux/boxmodels/common/porousmediaboxproblem.hh, dumux/decoupled/1p/diffusion/diffusionproblem...hh, dumux/decoupled/2p/impes/impesproblem2p.hh, dumux/decoupled/2p/transport/transportproblem2p.hh. - - - Flux variables: Renaming of members - "...AtIP" -> "...", + + - Flux variables: Renaming of members + "...AtIP" -> "...", "concentration..." -> "massFraction...", "molarConc..." -> "moleFraction..." - The "massFraction..." members have been deprecated, instead + The "massFraction..." members have been deprecated, instead "moleFraction..." should be used. Affected files: - dumux/boxmodels/1p2c/1p2cfluxvariables.hh, + dumux/boxmodels/1p2c/1p2cfluxvariables.hh, dumux/boxmodels/2p2c/2p2cfluxvariables.hh, dumux/boxmodels/mpnc/.../...fluxvariables.hh, dumux/freeflow/stokes.../stokes...fluxvariables.hh. - - Box models: The primaryVarWeight() functions are no longer used for the - evaluation of the relative error. + - Box models: The primaryVarWeight() functions are no longer used for the + evaluation of the relative error. - Element and FVElementGeometry: The elem_() and fvElemGeom_() member function - of BoxLocalResidual have been replaced by element_() and fvGeometry_(). - + of BoxLocalResidual have been replaced by element_() and fvGeometry_(). + - Primary variables: All "...primaryVar/s" member functions have been replaced - by "...priVar/s": - dumux/boxmodels/common/boxlocalresidual.hh, + by "...priVar/s": + dumux/boxmodels/common/boxlocalresidual.hh, dumux/boxmodels/common/boxvolumevariables.hh. - - Start functionality in dumux/common/start.hh: printUsageDGF and + - Start functionality in dumux/common/start.hh: printUsageDGF and printUsageGrid are no longer needed. - -* DELETED member functions, which have been deprecated in DuMuX 2.1: + +* DELETED member functions, which have been deprecated in DuMuX 2.1: - dumux/material/spatialparameters/boxspatialparameters1p.hh: extrusionFactorScv and extrusionFactorScvf, now part of the volume variables @@ -1242,7 +1440,7 @@ Differences Between DuMuX 2.1 and DuMuX 2.2 IMPETProblem2P2C(..., SpatialParameters&, ...) replaced by IMPETProblem2P2C(TimeManager&, ...), initSat(const GlobalPosition&, const Element&) replaced by initSat(const Element&) initConcentration(const GlobalPosition&, const Element&) replaced by initConcentration(const Element&) - + - DUMUX_DEPRECATED has been removed. diff --git a/CMakeLists.txt b/CMakeLists.txt index 2d6d97067d523c2b94ef40c96c9ccdb850f33c4c..a6a2f8270a656ca4626085edf3b48e57bc082b69 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -14,6 +14,7 @@ endif() #find dune-common and set the module path find_package(dune-common) + list(APPEND CMAKE_MODULE_PATH ${dune-common_MODULE_PATH} "${PROJECT_SOURCE_DIR}/cmake/modules") #include the dune macros @@ -30,7 +31,6 @@ add_subdirectory(cmake/modules) add_subdirectory(doc) add_subdirectory(dumux) add_subdirectory(test EXCLUDE_FROM_ALL) -add_subdirectory(tutorial EXCLUDE_FROM_ALL) # finalize the dune project, e.g. generating config.h etc. finalize_dune_project(GENERATE_CONFIG_H_CMAKE) diff --git a/LICENSE.md b/LICENSE.md index e46eaca34ba4c6c2919163471f43f92e1786be1a..793e56a24be68311108e3cc13ff6e715517cbc30 100644 --- a/LICENSE.md +++ b/LICENSE.md @@ -6,49 +6,60 @@ Copyright holders | Year | Name | |------------|----------------------------| -| 2016 | Sina Ackermann | +| 2016-2018 | Sina Ackermann | | 2010-2014 | Katherina Baber | -| 2015-2016 | Martin Beck | -| 2013-2016 | Beatrix Becker | +| 2015-2018 | Martin Beck | +| 2013-2018 | Beatrix Becker | | 2014 | Markus Blatt | | 2010 | Felix Bode | +| 2018 | Samuel Burbulla | | 2007-2011 | Yufei Cao | -| 2011-2016 | Holger Class | +| 2018 | Edward 'Ned' Coltman | +| 2011-2018 | Holger Class | | 2008-2013 | Melanie Darcis | | 2008-2009 | Onur Dogan | | 2009-2011 | Karin Erbertseder | | 2009-2014 | Benjamin Faigle | -| 2013-2016 | Thomas Fetzer | -| 2007-2016 | Bernd Flemisch | +| 2013-2018 | Thomas Fetzer | +| 2007-2018 | Bernd Flemisch | | 2007-2010 | Jochen Fritz | | 2015-2016 | Georg Futter | -| 2015-2016 | Dennis Gläser | -| 2012-2016 | Christoph Grüninger | -| 2016 | Katharina Heck | -| 2015-2016 | Johannes Hommel | +| 2015-2018 | Dennis Gläser | +| 2012-2018 | Christoph Grüninger | +| 2016-2018 | Katharina Heck | +| 2017 | Rainer Helmig | +| 2015-2018 | Johannes Hommel | | 2012-2015 | Vishal Jambhekar | | 2013-2014 | Muhammad Adil Javed | -| 2012-2016 | Alexander Kissinger | -| 2013-2016 | Timo Koch | +| 2012-2017 | Alexander Kissinger | +| 2013-2018 | Timo Koch | +| 2017 | Kata Kurgyis | +| 2018 | Theresa Kurz | | 2008-2012 | Andreas Lauser | +| 2018 | Giuliano Lambardo | +| 2018 | Melanie Lipp | +| 2018 | Farid Mohammadi | | 2008-2014 | Klaus Mosthaf | | 2009-2014 | Philipp Nuske | | 2014 | Mirka Papenheim | | 2013-2014 | Dominik Riesterer | | 2008 | Irina Rybak | -| 2013-2016 | Martin Schneider | -| 2015 | Simon Scholz | +| 2013-2018 | Martin Schneider | +| 2015-2018 | Simon Scholz | | 2009 | Anneli Schöniger | | 2015-2016 | Natalie Schröder | | 2010-2016 | Nicolas Schwenck | -| 2015-2016 | Gabriele Seitz | +| 2015-2018 | Gabriele Seitz | +| 2018 | Lincoln Sherpa | | 2011 | Michael Sinsbeck | | 2010 | Leopold Stadler | | 2012-2014 | Alexandru Tatomir | -| 2015-2016 | Larissa de Vries | +| 2015-2017 | Larissa de Vries | | 2013 | Katharina Türk | +| 2018 | Martin Utz | | 2010-2014 | Lena Walter | -| 2015-2016 | Kilian Weishaupt | +| 2018 | Felix Weinhardt | +| 2015-2018 | Kilian Weishaupt | | 2010-2011 | David Werner | | 2015 | Hao Wu | | 2008-2013 | Markus Wolff | @@ -59,7 +70,7 @@ License ------- DuMuX is licensed under the terms and conditions of the GNU General -Public License (GPL) version 2 or - at your option - any later +Public License (GPL) version 3 or - at your option - any later version. The GPL can be read [online][0], or below. Please note that DuMuX' license, unlike DUNE's, does NOT feature a @@ -68,287 +79,629 @@ you must publish any source code which uses any of the DuMuX header files if you want to redistribute your program to third parties. If this is unacceptable to you, please [contact us][1] for a commercial license. -[0]: http://www.gnu.org/licenses/old-licenses/gpl-2.0.html +[0]: https://www.gnu.org/licenses/gpl-3.0.en.html [1]: http://www.hydrosys.uni-stuttgart.de/index.en.php Complete License Text --------------------- -GNU General Public License -========================== +### GNU GENERAL PUBLIC LICENSE -_Version 2, June 1991_ -_Copyright © 1989, 1991 Free Software Foundation, Inc.,_ -_51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA_ +Version 3, 29 June 2007 -Everyone is permitted to copy and distribute verbatim copies -of this license document, but changing it is not allowed. +Copyright (C) 2007 Free Software Foundation, Inc. + + +Everyone is permitted to copy and distribute verbatim copies of this +license document, but changing it is not allowed. ### Preamble -The licenses for most software are designed to take away your -freedom to share and change it. By contrast, the GNU General Public -License is intended to guarantee your freedom to share and change free -software--to make sure the software is free for all its users. This -General Public License applies to most of the Free Software -Foundation's software and to any other program whose authors commit to -using it. (Some other Free Software Foundation software is covered by -the GNU Lesser General Public License instead.) You can apply it to -your programs, too. +The GNU General Public License is a free, copyleft license for +software and other kinds of works. + +The licenses for most software and other practical works are designed +to take away your freedom to share and change the works. By contrast, +the GNU General Public License is intended to guarantee your freedom +to share and change all versions of a program--to make sure it remains +free software for all its users. We, the Free Software Foundation, use +the GNU General Public License for most of our software; it applies +also to any other work released this way by its authors. You can apply +it to your programs, too. When we speak of free software, we are referring to freedom, not -price. Our General Public Licenses are designed to make sure that you +price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for -this service if you wish), that you receive source code or can get it -if you want it, that you can change the software or use pieces of it -in new free programs; and that you know you can do these things. +them if you wish), that you receive source code or can get it if you +want it, that you can change the software or use pieces of it in new +free programs, and that you know you can do these things. -To protect your rights, we need to make restrictions that forbid -anyone to deny you these rights or to ask you to surrender the rights. -These restrictions translate to certain responsibilities for you if you -distribute copies of the software, or if you modify it. +To protect your rights, we need to prevent others from denying you +these rights or asking you to surrender the rights. Therefore, you +have certain responsibilities if you distribute copies of the +software, or if you modify it: responsibilities to respect the freedom +of others. For example, if you distribute copies of such a program, whether -gratis or for a fee, you must give the recipients all the rights that -you have. You must make sure that they, too, receive or can get the -source code. And you must show them these terms so they know their -rights. - -We protect your rights with two steps: **(1)** copyright the software, and -**(2)** offer you this license which gives you legal permission to copy, -distribute and/or modify the software. - -Also, for each author's protection and ours, we want to make certain -that everyone understands that there is no warranty for this free -software. If the software is modified by someone else and passed on, we -want its recipients to know that what they have is not the original, so -that any problems introduced by others will not reflect on the original -authors' reputations. - -Finally, any free program is threatened constantly by software -patents. We wish to avoid the danger that redistributors of a free -program will individually obtain patent licenses, in effect making the -program proprietary. To prevent this, we have made it clear that any -patent must be licensed for everyone's free use or not licensed at all. +gratis or for a fee, you must pass on to the recipients the same +freedoms that you received. You must make sure that they, too, receive +or can get the source code. And you must show them these terms so they +know their rights. + +Developers that use the GNU GPL protect your rights with two steps: +(1) assert copyright on the software, and (2) offer you this License +giving you legal permission to copy, distribute and/or modify it. + +For the developers' and authors' protection, the GPL clearly explains +that there is no warranty for this free software. For both users' and +authors' sake, the GPL requires that modified versions be marked as +changed, so that their problems will not be attributed erroneously to +authors of previous versions. + +Some devices are designed to deny users access to install or run +modified versions of the software inside them, although the +manufacturer can do so. This is fundamentally incompatible with the +aim of protecting users' freedom to change the software. The +systematic pattern of such abuse occurs in the area of products for +individuals to use, which is precisely where it is most unacceptable. +Therefore, we have designed this version of the GPL to prohibit the +practice for those products. If such problems arise substantially in +other domains, we stand ready to extend this provision to those +domains in future versions of the GPL, as needed to protect the +freedom of users. + +Finally, every program is threatened constantly by software patents. +States should not allow patents to restrict development and use of +software on general-purpose computers, but in those that do, we wish +to avoid the special danger that patents applied to a free program +could make it effectively proprietary. To prevent this, the GPL +assures that patents cannot be used to render the program non-free. The precise terms and conditions for copying, distribution and modification follow. -### TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION - -**0.** This License applies to any program or other work which contains -a notice placed by the copyright holder saying it may be distributed -under the terms of this General Public License. The “Program”, below, -refers to any such program or work, and a “work based on the Program” -means either the Program or any derivative work under copyright law: -that is to say, a work containing the Program or a portion of it, -either verbatim or with modifications and/or translated into another -language. (Hereinafter, translation is included without limitation in -the term “modification”.) Each licensee is addressed as “you”. - -Activities other than copying, distribution and modification are not -covered by this License; they are outside its scope. The act of -running the Program is not restricted, and the output from the Program -is covered only if its contents constitute a work based on the -Program (independent of having been made by running the Program). -Whether that is true depends on what the Program does. - -**1.** You may copy and distribute verbatim copies of the Program's -source code as you receive it, in any medium, provided that you -conspicuously and appropriately publish on each copy an appropriate -copyright notice and disclaimer of warranty; keep intact all the -notices that refer to this License and to the absence of any warranty; -and give any other recipients of the Program a copy of this License -along with the Program. - -You may charge a fee for the physical act of transferring a copy, and -you may at your option offer warranty protection in exchange for a fee. - -**2.** You may modify your copy or copies of the Program or any portion -of it, thus forming a work based on the Program, and copy and -distribute such modifications or work under the terms of Section 1 -above, provided that you also meet all of these conditions: - -* **a)** You must cause the modified files to carry prominent notices -stating that you changed the files and the date of any change. -* **b)** You must cause any work that you distribute or publish, that in -whole or in part contains or is derived from the Program or any -part thereof, to be licensed as a whole at no charge to all third -parties under the terms of this License. -* **c)** If the modified program normally reads commands interactively -when run, you must cause it, when started running for such -interactive use in the most ordinary way, to print or display an -announcement including an appropriate copyright notice and a -notice that there is no warranty (or else, saying that you provide -a warranty) and that users may redistribute the program under -these conditions, and telling the user how to view a copy of this -License. (Exception: if the Program itself is interactive but -does not normally print such an announcement, your work based on -the Program is not required to print an announcement.) - -These requirements apply to the modified work as a whole. If -identifiable sections of that work are not derived from the Program, -and can be reasonably considered independent and separate works in -themselves, then this License, and its terms, do not apply to those -sections when you distribute them as separate works. But when you -distribute the same sections as part of a whole which is a work based -on the Program, the distribution of the whole must be on the terms of -this License, whose permissions for other licensees extend to the -entire whole, and thus to each and every part regardless of who wrote it. - -Thus, it is not the intent of this section to claim rights or contest -your rights to work written entirely by you; rather, the intent is to -exercise the right to control the distribution of derivative or -collective works based on the Program. - -In addition, mere aggregation of another work not based on the Program -with the Program (or with a work based on the Program) on a volume of -a storage or distribution medium does not bring the other work under -the scope of this License. - -**3.** You may copy and distribute the Program (or a work based on it, -under Section 2) in object code or executable form under the terms of -Sections 1 and 2 above provided that you also do one of the following: - -* **a)** Accompany it with the complete corresponding machine-readable -source code, which must be distributed under the terms of Sections -1 and 2 above on a medium customarily used for software interchange; or, -* **b)** Accompany it with a written offer, valid for at least three -years, to give any third party, for a charge no more than your -cost of physically performing source distribution, a complete -machine-readable copy of the corresponding source code, to be -distributed under the terms of Sections 1 and 2 above on a medium -customarily used for software interchange; or, -* **c)** Accompany it with the information you received as to the offer -to distribute corresponding source code. (This alternative is -allowed only for noncommercial distribution and only if you -received the program in object code or executable form with such -an offer, in accord with Subsection b above.) - -The source code for a work means the preferred form of the work for -making modifications to it. For an executable work, complete source -code means all the source code for all modules it contains, plus any -associated interface definition files, plus the scripts used to -control compilation and installation of the executable. However, as a -special exception, the source code distributed need not include -anything that is normally distributed (in either source or binary -form) with the major components (compiler, kernel, and so on) of the -operating system on which the executable runs, unless that component -itself accompanies the executable. - -If distribution of executable or object code is made by offering -access to copy from a designated place, then offering equivalent -access to copy the source code from the same place counts as -distribution of the source code, even though third parties are not -compelled to copy the source along with the object code. - -**4.** You may not copy, modify, sublicense, or distribute the Program -except as expressly provided under this License. Any attempt -otherwise to copy, modify, sublicense or distribute the Program is -void, and will automatically terminate your rights under this License. -However, parties who have received copies, or rights, from you under -this License will not have their licenses terminated so long as such -parties remain in full compliance. - -**5.** You are not required to accept this License, since you have not -signed it. However, nothing else grants you permission to modify or -distribute the Program or its derivative works. These actions are -prohibited by law if you do not accept this License. Therefore, by -modifying or distributing the Program (or any work based on the -Program), you indicate your acceptance of this License to do so, and -all its terms and conditions for copying, distributing or modifying -the Program or works based on it. - -**6.** Each time you redistribute the Program (or any work based on the -Program), the recipient automatically receives a license from the -original licensor to copy, distribute or modify the Program subject to -these terms and conditions. You may not impose any further -restrictions on the recipients' exercise of the rights granted herein. -You are not responsible for enforcing compliance by third parties to +### TERMS AND CONDITIONS + +#### 0. Definitions. + +"This License" refers to version 3 of the GNU General Public License. + +"Copyright" also means copyright-like laws that apply to other kinds +of works, such as semiconductor masks. + +"The Program" refers to any copyrightable work licensed under this +License. Each licensee is addressed as "you". "Licensees" and +"recipients" may be individuals or organizations. + +To "modify" a work means to copy from or adapt all or part of the work +in a fashion requiring copyright permission, other than the making of +an exact copy. The resulting work is called a "modified version" of +the earlier work or a work "based on" the earlier work. + +A "covered work" means either the unmodified Program or a work based +on the Program. + +To "propagate" a work means to do anything with it that, without +permission, would make you directly or secondarily liable for +infringement under applicable copyright law, except executing it on a +computer or modifying a private copy. Propagation includes copying, +distribution (with or without modification), making available to the +public, and in some countries other activities as well. + +To "convey" a work means any kind of propagation that enables other +parties to make or receive copies. Mere interaction with a user +through a computer network, with no transfer of a copy, is not +conveying. + +An interactive user interface displays "Appropriate Legal Notices" to +the extent that it includes a convenient and prominently visible +feature that (1) displays an appropriate copyright notice, and (2) +tells the user that there is no warranty for the work (except to the +extent that warranties are provided), that licensees may convey the +work under this License, and how to view a copy of this License. If +the interface presents a list of user commands or options, such as a +menu, a prominent item in the list meets this criterion. + +#### 1. Source Code. + +The "source code" for a work means the preferred form of the work for +making modifications to it. "Object code" means any non-source form of +a work. + +A "Standard Interface" means an interface that either is an official +standard defined by a recognized standards body, or, in the case of +interfaces specified for a particular programming language, one that +is widely used among developers working in that language. + +The "System Libraries" of an executable work include anything, other +than the work as a whole, that (a) is included in the normal form of +packaging a Major Component, but which is not part of that Major +Component, and (b) serves only to enable use of the work with that +Major Component, or to implement a Standard Interface for which an +implementation is available to the public in source code form. A +"Major Component", in this context, means a major essential component +(kernel, window system, and so on) of the specific operating system +(if any) on which the executable work runs, or a compiler used to +produce the work, or an object code interpreter used to run it. + +The "Corresponding Source" for a work in object code form means all +the source code needed to generate, install, and (for an executable +work) run the object code and to modify the work, including scripts to +control those activities. However, it does not include the work's +System Libraries, or general-purpose tools or generally available free +programs which are used unmodified in performing those activities but +which are not part of the work. For example, Corresponding Source +includes interface definition files associated with source files for +the work, and the source code for shared libraries and dynamically +linked subprograms that the work is specifically designed to require, +such as by intimate data communication or control flow between those +subprograms and other parts of the work. + +The Corresponding Source need not include anything that users can +regenerate automatically from other parts of the Corresponding Source. + +The Corresponding Source for a work in source code form is that same +work. + +#### 2. Basic Permissions. + +All rights granted under this License are granted for the term of +copyright on the Program, and are irrevocable provided the stated +conditions are met. This License explicitly affirms your unlimited +permission to run the unmodified Program. The output from running a +covered work is covered by this License only if the output, given its +content, constitutes a covered work. This License acknowledges your +rights of fair use or other equivalent, as provided by copyright law. + +You may make, run and propagate covered works that you do not convey, +without conditions so long as your license otherwise remains in force. +You may convey covered works to others for the sole purpose of having +them make modifications exclusively for you, or provide you with +facilities for running those works, provided that you comply with the +terms of this License in conveying all material for which you do not +control copyright. Those thus making or running the covered works for +you must do so exclusively on your behalf, under your direction and +control, on terms that prohibit them from making any copies of your +copyrighted material outside their relationship with you. + +Conveying under any other circumstances is permitted solely under the +conditions stated below. Sublicensing is not allowed; section 10 makes +it unnecessary. + +#### 3. Protecting Users' Legal Rights From Anti-Circumvention Law. + +No covered work shall be deemed part of an effective technological +measure under any applicable law fulfilling obligations under article +11 of the WIPO copyright treaty adopted on 20 December 1996, or +similar laws prohibiting or restricting circumvention of such +measures. + +When you convey a covered work, you waive any legal power to forbid +circumvention of technological measures to the extent such +circumvention is effected by exercising rights under this License with +respect to the covered work, and you disclaim any intention to limit +operation or modification of the work as a means of enforcing, against +the work's users, your or third parties' legal rights to forbid +circumvention of technological measures. + +#### 4. Conveying Verbatim Copies. + +You may convey verbatim copies of the Program's source code as you +receive it, in any medium, provided that you conspicuously and +appropriately publish on each copy an appropriate copyright notice; +keep intact all notices stating that this License and any +non-permissive terms added in accord with section 7 apply to the code; +keep intact all notices of the absence of any warranty; and give all +recipients a copy of this License along with the Program. + +You may charge any price or no price for each copy that you convey, +and you may offer support or warranty protection for a fee. + +#### 5. Conveying Modified Source Versions. + +You may convey a work based on the Program, or the modifications to +produce it from the Program, in the form of source code under the +terms of section 4, provided that you also meet all of these +conditions: + +- a) The work must carry prominent notices stating that you modified + it, and giving a relevant date. +- b) The work must carry prominent notices stating that it is + released under this License and any conditions added under + section 7. This requirement modifies the requirement in section 4 + to "keep intact all notices". +- c) You must license the entire work, as a whole, under this + License to anyone who comes into possession of a copy. This + License will therefore apply, along with any applicable section 7 + additional terms, to the whole of the work, and all its parts, + regardless of how they are packaged. This License gives no + permission to license the work in any other way, but it does not + invalidate such permission if you have separately received it. +- d) If the work has interactive user interfaces, each must display + Appropriate Legal Notices; however, if the Program has interactive + interfaces that do not display Appropriate Legal Notices, your + work need not make them do so. + +A compilation of a covered work with other separate and independent +works, which are not by their nature extensions of the covered work, +and which are not combined with it such as to form a larger program, +in or on a volume of a storage or distribution medium, is called an +"aggregate" if the compilation and its resulting copyright are not +used to limit the access or legal rights of the compilation's users +beyond what the individual works permit. Inclusion of a covered work +in an aggregate does not cause this License to apply to the other +parts of the aggregate. + +#### 6. Conveying Non-Source Forms. + +You may convey a covered work in object code form under the terms of +sections 4 and 5, provided that you also convey the machine-readable +Corresponding Source under the terms of this License, in one of these +ways: + +- a) Convey the object code in, or embodied in, a physical product + (including a physical distribution medium), accompanied by the + Corresponding Source fixed on a durable physical medium + customarily used for software interchange. +- b) Convey the object code in, or embodied in, a physical product + (including a physical distribution medium), accompanied by a + written offer, valid for at least three years and valid for as + long as you offer spare parts or customer support for that product + model, to give anyone who possesses the object code either (1) a + copy of the Corresponding Source for all the software in the + product that is covered by this License, on a durable physical + medium customarily used for software interchange, for a price no + more than your reasonable cost of physically performing this + conveying of source, or (2) access to copy the Corresponding + Source from a network server at no charge. +- c) Convey individual copies of the object code with a copy of the + written offer to provide the Corresponding Source. This + alternative is allowed only occasionally and noncommercially, and + only if you received the object code with such an offer, in accord + with subsection 6b. +- d) Convey the object code by offering access from a designated + place (gratis or for a charge), and offer equivalent access to the + Corresponding Source in the same way through the same place at no + further charge. You need not require recipients to copy the + Corresponding Source along with the object code. If the place to + copy the object code is a network server, the Corresponding Source + may be on a different server (operated by you or a third party) + that supports equivalent copying facilities, provided you maintain + clear directions next to the object code saying where to find the + Corresponding Source. Regardless of what server hosts the + Corresponding Source, you remain obligated to ensure that it is + available for as long as needed to satisfy these requirements. +- e) Convey the object code using peer-to-peer transmission, + provided you inform other peers where the object code and + Corresponding Source of the work are being offered to the general + public at no charge under subsection 6d. + +A separable portion of the object code, whose source code is excluded +from the Corresponding Source as a System Library, need not be +included in conveying the object code work. + +A "User Product" is either (1) a "consumer product", which means any +tangible personal property which is normally used for personal, +family, or household purposes, or (2) anything designed or sold for +incorporation into a dwelling. In determining whether a product is a +consumer product, doubtful cases shall be resolved in favor of +coverage. For a particular product received by a particular user, +"normally used" refers to a typical or common use of that class of +product, regardless of the status of the particular user or of the way +in which the particular user actually uses, or expects or is expected +to use, the product. A product is a consumer product regardless of +whether the product has substantial commercial, industrial or +non-consumer uses, unless such uses represent the only significant +mode of use of the product. + +"Installation Information" for a User Product means any methods, +procedures, authorization keys, or other information required to +install and execute modified versions of a covered work in that User +Product from a modified version of its Corresponding Source. The +information must suffice to ensure that the continued functioning of +the modified object code is in no case prevented or interfered with +solely because modification has been made. + +If you convey an object code work under this section in, or with, or +specifically for use in, a User Product, and the conveying occurs as +part of a transaction in which the right of possession and use of the +User Product is transferred to the recipient in perpetuity or for a +fixed term (regardless of how the transaction is characterized), the +Corresponding Source conveyed under this section must be accompanied +by the Installation Information. But this requirement does not apply +if neither you nor any third party retains the ability to install +modified object code on the User Product (for example, the work has +been installed in ROM). + +The requirement to provide Installation Information does not include a +requirement to continue to provide support service, warranty, or +updates for a work that has been modified or installed by the +recipient, or for the User Product in which it has been modified or +installed. Access to a network may be denied when the modification +itself materially and adversely affects the operation of the network +or violates the rules and protocols for communication across the +network. + +Corresponding Source conveyed, and Installation Information provided, +in accord with this section must be in a format that is publicly +documented (and with an implementation available to the public in +source code form), and must require no special password or key for +unpacking, reading or copying. + +#### 7. Additional Terms. + +"Additional permissions" are terms that supplement the terms of this +License by making exceptions from one or more of its conditions. +Additional permissions that are applicable to the entire Program shall +be treated as though they were included in this License, to the extent +that they are valid under applicable law. If additional permissions +apply only to part of the Program, that part may be used separately +under those permissions, but the entire Program remains governed by +this License without regard to the additional permissions. + +When you convey a copy of a covered work, you may at your option +remove any additional permissions from that copy, or from any part of +it. (Additional permissions may be written to require their own +removal in certain cases when you modify the work.) You may place +additional permissions on material, added by you to a covered work, +for which you have or can give appropriate copyright permission. + +Notwithstanding any other provision of this License, for material you +add to a covered work, you may (if authorized by the copyright holders +of that material) supplement the terms of this License with terms: + +- a) Disclaiming warranty or limiting liability differently from the + terms of sections 15 and 16 of this License; or +- b) Requiring preservation of specified reasonable legal notices or + author attributions in that material or in the Appropriate Legal + Notices displayed by works containing it; or +- c) Prohibiting misrepresentation of the origin of that material, + or requiring that modified versions of such material be marked in + reasonable ways as different from the original version; or +- d) Limiting the use for publicity purposes of names of licensors + or authors of the material; or +- e) Declining to grant rights under trademark law for use of some + trade names, trademarks, or service marks; or +- f) Requiring indemnification of licensors and authors of that + material by anyone who conveys the material (or modified versions + of it) with contractual assumptions of liability to the recipient, + for any liability that these contractual assumptions directly + impose on those licensors and authors. + +All other non-permissive additional terms are considered "further +restrictions" within the meaning of section 10. If the Program as you +received it, or any part of it, contains a notice stating that it is +governed by this License along with a term that is a further +restriction, you may remove that term. If a license document contains +a further restriction but permits relicensing or conveying under this +License, you may add to a covered work material governed by the terms +of that license document, provided that the further restriction does +not survive such relicensing or conveying. + +If you add terms to a covered work in accord with this section, you +must place, in the relevant source files, a statement of the +additional terms that apply to those files, or a notice indicating +where to find the applicable terms. + +Additional terms, permissive or non-permissive, may be stated in the +form of a separately written license, or stated as exceptions; the +above requirements apply either way. + +#### 8. Termination. + +You may not propagate or modify a covered work except as expressly +provided under this License. Any attempt otherwise to propagate or +modify it is void, and will automatically terminate your rights under +this License (including any patent licenses granted under the third +paragraph of section 11). + +However, if you cease all violation of this License, then your license +from a particular copyright holder is reinstated (a) provisionally, +unless and until the copyright holder explicitly and finally +terminates your license, and (b) permanently, if the copyright holder +fails to notify you of the violation by some reasonable means prior to +60 days after the cessation. + +Moreover, your license from a particular copyright holder is +reinstated permanently if the copyright holder notifies you of the +violation by some reasonable means, this is the first time you have +received notice of violation of this License (for any work) from that +copyright holder, and you cure the violation prior to 30 days after +your receipt of the notice. + +Termination of your rights under this section does not terminate the +licenses of parties who have received copies or rights from you under +this License. If your rights have been terminated and not permanently +reinstated, you do not qualify to receive new licenses for the same +material under section 10. + +#### 9. Acceptance Not Required for Having Copies. + +You are not required to accept this License in order to receive or run +a copy of the Program. Ancillary propagation of a covered work +occurring solely as a consequence of using peer-to-peer transmission +to receive a copy likewise does not require acceptance. However, +nothing other than this License grants you permission to propagate or +modify any covered work. These actions infringe copyright if you do +not accept this License. Therefore, by modifying or propagating a +covered work, you indicate your acceptance of this License to do so. + +#### 10. Automatic Licensing of Downstream Recipients. + +Each time you convey a covered work, the recipient automatically +receives a license from the original licensors, to run, modify and +propagate that work, subject to this License. You are not responsible +for enforcing compliance by third parties with this License. + +An "entity transaction" is a transaction transferring control of an +organization, or substantially all assets of one, or subdividing an +organization, or merging organizations. If propagation of a covered +work results from an entity transaction, each party to that +transaction who receives a copy of the work also receives whatever +licenses to the work the party's predecessor in interest had or could +give under the previous paragraph, plus a right to possession of the +Corresponding Source of the work from the predecessor in interest, if +the predecessor has it or can get it with reasonable efforts. + +You may not impose any further restrictions on the exercise of the +rights granted or affirmed under this License. For example, you may +not impose a license fee, royalty, or other charge for exercise of +rights granted under this License, and you may not initiate litigation +(including a cross-claim or counterclaim in a lawsuit) alleging that +any patent claim is infringed by making, using, selling, offering for +sale, or importing the Program or any portion of it. + +#### 11. Patents. + +A "contributor" is a copyright holder who authorizes use under this +License of the Program or a work on which the Program is based. The +work thus licensed is called the contributor's "contributor version". + +A contributor's "essential patent claims" are all patent claims owned +or controlled by the contributor, whether already acquired or +hereafter acquired, that would be infringed by some manner, permitted +by this License, of making, using, or selling its contributor version, +but do not include claims that would be infringed only as a +consequence of further modification of the contributor version. For +purposes of this definition, "control" includes the right to grant +patent sublicenses in a manner consistent with the requirements of this License. -**7.** If, as a consequence of a court judgment or allegation of patent -infringement or for any other reason (not limited to patent issues), -conditions are imposed on you (whether by court order, agreement or +Each contributor grants you a non-exclusive, worldwide, royalty-free +patent license under the contributor's essential patent claims, to +make, use, sell, offer for sale, import and otherwise run, modify and +propagate the contents of its contributor version. + +In the following three paragraphs, a "patent license" is any express +agreement or commitment, however denominated, not to enforce a patent +(such as an express permission to practice a patent or covenant not to +sue for patent infringement). To "grant" such a patent license to a +party means to make such an agreement or commitment not to enforce a +patent against the party. + +If you convey a covered work, knowingly relying on a patent license, +and the Corresponding Source of the work is not available for anyone +to copy, free of charge and under the terms of this License, through a +publicly available network server or other readily accessible means, +then you must either (1) cause the Corresponding Source to be so +available, or (2) arrange to deprive yourself of the benefit of the +patent license for this particular work, or (3) arrange, in a manner +consistent with the requirements of this License, to extend the patent +license to downstream recipients. "Knowingly relying" means you have +actual knowledge that, but for the patent license, your conveying the +covered work in a country, or your recipient's use of the covered work +in a country, would infringe one or more identifiable patents in that +country that you have reason to believe are valid. + +If, pursuant to or in connection with a single transaction or +arrangement, you convey, or propagate by procuring conveyance of, a +covered work, and grant a patent license to some of the parties +receiving the covered work authorizing them to use, propagate, modify +or convey a specific copy of the covered work, then the patent license +you grant is automatically extended to all recipients of the covered +work and works based on it. + +A patent license is "discriminatory" if it does not include within the +scope of its coverage, prohibits the exercise of, or is conditioned on +the non-exercise of one or more of the rights that are specifically +granted under this License. You may not convey a covered work if you +are a party to an arrangement with a third party that is in the +business of distributing software, under which you make payment to the +third party based on the extent of your activity of conveying the +work, and under which the third party grants, to any of the parties +who would receive the covered work from you, a discriminatory patent +license (a) in connection with copies of the covered work conveyed by +you (or copies made from those copies), or (b) primarily for and in +connection with specific products or compilations that contain the +covered work, unless you entered into that arrangement, or that patent +license was granted, prior to 28 March 2007. + +Nothing in this License shall be construed as excluding or limiting +any implied license or other defenses to infringement that may +otherwise be available to you under applicable patent law. + +#### 12. No Surrender of Others' Freedom. + +If conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not -excuse you from the conditions of this License. If you cannot -distribute so as to satisfy simultaneously your obligations under this -License and any other pertinent obligations, then as a consequence you -may not distribute the Program at all. For example, if a patent -license would not permit royalty-free redistribution of the Program by -all those who receive copies directly or indirectly through you, then -the only way you could satisfy both it and this License would be to -refrain entirely from distribution of the Program. - -If any portion of this section is held invalid or unenforceable under -any particular circumstance, the balance of the section is intended to -apply and the section as a whole is intended to apply in other -circumstances. - -It is not the purpose of this section to induce you to infringe any -patents or other property right claims or to contest validity of any -such claims; this section has the sole purpose of protecting the -integrity of the free software distribution system, which is -implemented by public license practices. Many people have made -generous contributions to the wide range of software distributed -through that system in reliance on consistent application of that -system; it is up to the author/donor to decide if he or she is willing -to distribute software through any other system and a licensee cannot -impose that choice. - -This section is intended to make thoroughly clear what is believed to -be a consequence of the rest of this License. - -**8.** If the distribution and/or use of the Program is restricted in -certain countries either by patents or by copyrighted interfaces, the -original copyright holder who places the Program under this License -may add an explicit geographical distribution limitation excluding -those countries, so that distribution is permitted only in or among -countries not thus excluded. In such case, this License incorporates -the limitation as if written in the body of this License. - -**9.** The Free Software Foundation may publish revised and/or new versions -of the General Public License from time to time. Such new versions will -be similar in spirit to the present version, but may differ in detail to -address new problems or concerns. - -Each version is given a distinguishing version number. If the Program -specifies a version number of this License which applies to it and “any -later version”, you have the option of following the terms and conditions -either of that version or of any later version published by the Free -Software Foundation. If the Program does not specify a version number of -this License, you may choose any version ever published by the Free Software -Foundation. - -**10.** If you wish to incorporate parts of the Program into other free -programs whose distribution conditions are different, write to the author -to ask for permission. For software which is copyrighted by the Free -Software Foundation, write to the Free Software Foundation; we sometimes -make exceptions for this. Our decision will be guided by the two goals -of preserving the free status of all derivatives of our free software and -of promoting the sharing and reuse of software generally. - -### NO WARRANTY - -**11.** BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY -FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN -OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES -PROVIDE THE PROGRAM “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED -OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF -MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS -TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE -PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, -REPAIR OR CORRECTION. - -**12.** IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING -WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR -REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, -INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING -OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED -TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY -YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER -PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE -POSSIBILITY OF SUCH DAMAGES. +excuse you from the conditions of this License. If you cannot convey a +covered work so as to satisfy simultaneously your obligations under +this License and any other pertinent obligations, then as a +consequence you may not convey it at all. For example, if you agree to +terms that obligate you to collect a royalty for further conveying +from those to whom you convey the Program, the only way you could +satisfy both those terms and this License would be to refrain entirely +from conveying the Program. + +#### 13. Use with the GNU Affero General Public License. + +Notwithstanding any other provision of this License, you have +permission to link or combine any covered work with a work licensed +under version 3 of the GNU Affero General Public License into a single +combined work, and to convey the resulting work. The terms of this +License will continue to apply to the part which is the covered work, +but the special requirements of the GNU Affero General Public License, +section 13, concerning interaction through a network will apply to the +combination as such. + +#### 14. Revised Versions of this License. + +The Free Software Foundation may publish revised and/or new versions +of the GNU General Public License from time to time. Such new versions +will be similar in spirit to the present version, but may differ in +detail to address new problems or concerns. + +Each version is given a distinguishing version number. If the Program +specifies that a certain numbered version of the GNU General Public +License "or any later version" applies to it, you have the option of +following the terms and conditions either of that numbered version or +of any later version published by the Free Software Foundation. If the +Program does not specify a version number of the GNU General Public +License, you may choose any version ever published by the Free +Software Foundation. + +If the Program specifies that a proxy can decide which future versions +of the GNU General Public License can be used, that proxy's public +statement of acceptance of a version permanently authorizes you to +choose that version for the Program. + +Later license versions may give you additional or different +permissions. However, no additional obligations are imposed on any +author or copyright holder as a result of your choosing to follow a +later version. + +#### 15. Disclaimer of Warranty. + +THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY +APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT +HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT +WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT +LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND +PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE +DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR +CORRECTION. + +#### 16. Limitation of Liability. + +IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR +CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, +INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES +ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT +NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR +LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM +TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER +PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. + +#### 17. Interpretation of Sections 15 and 16. + +If the disclaimer of warranty and limitation of liability provided +above cannot be given local legal effect according to their terms, +reviewing courts shall apply local law that most closely approximates +an absolute waiver of all civil liability in connection with the +Program, unless a warranty or assumption of liability accompanies a +copy of the Program in return for a fee. END OF TERMS AND CONDITIONS @@ -356,57 +709,54 @@ END OF TERMS AND CONDITIONS If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it -free software which everyone can redistribute and change under these terms. - -To do so, attach the following notices to the program. It is safest -to attach them to the start of each source file to most effectively -convey the exclusion of warranty; and each file should have at least -the “copyright” line and a pointer to where the full notice is found. - - - Copyright (C) - - This program is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 2 of the License, or - (at your option) any later version. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License along - with this program; if not, write to the Free Software Foundation, Inc., - 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. - -Also add information on how to contact you by electronic and paper mail. - -If the program is interactive, make it output a short notice like this -when it starts in an interactive mode: - - Gnomovision version 69, Copyright (C) year name of author - Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. - This is free software, and you are welcome to redistribute it - under certain conditions; type `show c' for details. - -The hypothetical commands `show w` and `show c` should show the appropriate -parts of the General Public License. Of course, the commands you use may -be called something other than `show w` and `show c`; they could even be -mouse-clicks or menu items--whatever suits your program. - -You should also get your employer (if you work as a programmer) or your -school, if any, to sign a “copyright disclaimer” for the program, if -necessary. Here is a sample; alter the names: - - Yoyodyne, Inc., hereby disclaims all copyright interest in the program - `Gnomovision' (which makes passes at compilers) written by James Hacker. - - , 1 April 1989 - Ty Coon, President of Vice - -This General Public License does not permit incorporating your program into -proprietary programs. If your program is a subroutine library, you may -consider it more useful to permit linking proprietary applications with the -library. If this is what you want to do, use the GNU Lesser General -Public License instead of this License. +free software which everyone can redistribute and change under these +terms. + +To do so, attach the following notices to the program. It is safest to +attach them to the start of each source file to most effectively state +the exclusion of warranty; and each file should have at least the +"copyright" line and a pointer to where the full notice is found. + + + Copyright (C) + + This program is free software: you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation, either version 3 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see . + +Also add information on how to contact you by electronic and paper +mail. + +If the program does terminal interaction, make it output a short +notice like this when it starts in an interactive mode: + + Copyright (C) + This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'. + This is free software, and you are welcome to redistribute it + under certain conditions; type `show c' for details. + +The hypothetical commands \`show w' and \`show c' should show the +appropriate parts of the General Public License. Of course, your +program's commands might be different; for a GUI interface, you would +use an "about box". + +You should also get your employer (if you work as a programmer) or +school, if any, to sign a "copyright disclaimer" for the program, if +necessary. For more information on this, and how to apply and follow +the GNU GPL, see . + +The GNU General Public License does not permit incorporating your +program into proprietary programs. If your program is a subroutine +library, you may consider it more useful to permit linking proprietary +applications with the library. If this is what you want to do, use the +GNU Lesser General Public License instead of this License. But first, +please read . diff --git a/README.md b/README.md index dfd5bbce2346b5fe180cbf7ca2f774fe50cf42b6..8bf15d1ea7cc7ca993d37a4674e26563dc9c91b7 100644 --- a/README.md +++ b/README.md @@ -15,16 +15,16 @@ description of the goals and motivations behind DuMuX. Installation =============== -Have a look at the [installation guide][3] or use the [DuMuX handbook] -[4], chapter 2. +Have a look at the [installation guide][3] or use the [DuMuX handbook][4], +Chapter 2. License ======== DuMuX is licensed under the terms and conditions of the GNU General -Public License (GPL) version 2 or - at your option - any later -version. The GPL can be [read online][5] or in the `LICENSE.md` file +Public License (GPL) version 3 or - at your option - any later +version. The GPL can be [read online][5] or in the [LICENSE.md](LICENSE.md) file provided in the topmost directory of the DuMuX source code tree. Please note that DuMuX' license, unlike DUNE's, does *not* feature a @@ -34,10 +34,11 @@ files if you want to redistribute your program to third parties. If this is unacceptable to you, please [contact us][6] for a commercial license. -See the file `LICENSE.md` for full copying permissions. +See the file [LICENSE.md](LICENSE.md) for full copying permissions. Automated Testing ================== +[![buildbot badge](https://git.iws.uni-stuttgart.de/buildbot/badges/dumux-master-dune-latest-gcc.svg)](https://git.iws.uni-stuttgart.de/buildbot/#/builders) DuMuX features many tests (some unit tests and test problems) that can be run manually. We have experimental support for automated testing with buildbot. @@ -45,11 +46,29 @@ Click Using install script: $INSTALL_DEP_SCRIPT to install dependencies for module $MODULE_NAME." - -# make it executable -chmod +x $INSTALL_DEP_SCRIPT - -# make a docker folder -if [ -d docker ]; then - echo "" - read -p " A docker folder already exists. Continue anyway? - will be overwritten - [y/N] " DELETE - echo "" - if test x$DELETE = xy -o x$DELETE = xY; then - rm -r docker - echo "--> Deleted old docker folder." - else - echo "Abort." - exit 1 - fi -fi - -# dockerignore file -if [ -e .dockerignore ]; then - rm .dockerignore -fi -touch .dockerignore -echo "build*" >> .dockerignore -echo "CMakeFiles" >> .dockerignore -echo "--> Created dockerignore file." - -mkdir docker -cd docker - -# also copy it here in case we build here -cp ../.dockerignore . - -# setpermissions helper script -touch setpermissions.sh -cat <> setpermissions.sh -#!/bin/bash -# The user can pass the user and group id by passing -# --env HOST_UID=\$(id -u \$USER) --env HOST_GID=\$(id -g \$USER) -# with the UID on the host to the container. Should work for Linux, Mac and Windows. -# Allows to manage the writes for shared volumes. -if [ "\$HOST_UID" ]; then - usermod -u \$HOST_UID dumux -fi -if [ "\$HOST_GID" ]; then - groupmod -g \$HOST_GID dumux -fi -# Make sure that everything in /dumux is accessible by the dumux user -# sed "1d" removes forst line which is the folder itself -# exclude the shared folder using grep. This folder should be accessible by setting the UID/GID. -# chown transfers ownership to group dumux user dumux -# the OR true trick avoids the script exiting due to use of set -e -find /dumux -maxdepth 1 | sed "1d" | grep -v "/dumux/shared" | xargs chown -R dumux:dumux 2> /dev/null || true - -EOT - -echo "--> Created permission helper script for easier container setup." - -touch WELCOME -cat <> WELCOME -Welcome to the dumux-pub Docker container $MODULE_NAME. You can run pre-compiled examples -in the folder $MODULE_NAME/build-cmake/appl, or compile them there using make . -The container doesn't have graphics support. -Copying the output like VTK files to the folder /dumux/shared will make them available -outside this container on the host for display. -EOT - -echo "--> Created welcome message displayed on Docker container startup." - -touch README.md -cat <> README.md -# readme for the dumux pub table $MODULE_NAME - -You created a Docker image $DOCKER_TAG. Next steps: - -* Try your container by running pubtable_$DOCKER_TAG open - See below for instructions how to share files with the host system. - -* Push the docker image to DockerHub or the GitLab Docker registry of your dumux-pub module. - Look at the Registry tab of your dumux-pub module for help. - -* Replace the image name in pubtable_$DOCKER_TAG with the actual image name - e.g. git.iws.uni-stuttgart.de:4567/dumux-pub/koch2017a. - -* [Optional] Add the Dockerfile to the git repository. - -* Add the pubtable_$DOCKER_TAG script to the git repository (this is for the user) - and add the following lines to your README.md: - -Using the pub table $MODULE_NAME with docker -============================================= - -In order to run simulations of this pub table look -at the convenience script pubtable_$DOCKER_TAG. -First download the script from the git repository. - -The simplest way is to spin up a container -is creating a new folder "dumux" -$ mkdir dumux -change to the new folder -$ cd dumux -and open the pub table by running -$ pubtable_$DOCKER_TAG open - -The container will spin up. It will mount the "dumux" -directory into the container at /dumux/shared. Put files -in this folder to share them with the host machine. This -could be e.g. VTK files produced by the simulation that -you want to visualize on the host machine. - -EOT - -echo "--> Created README.md on how to use the docker image." - -touch pubtable_$DOCKER_TAG -chmod +x pubtable_$DOCKER_TAG -cat <> pubtable_$DOCKER_TAG -#!/usr/bin/env bash - -# TODO set the image name here to a global address -# e.g. 'git.iws.uni-stuttgart.de:4567/dumux-pub/koch2017a' -PUB_IMAGE_NAME=$DOCKER_TAG - -# the host directory that is mounted into... -SHARED_DIR_HOST="\$(pwd)" -# ...this container directory. -SHARED_DIR_CONTAINER="/dumux/shared" - -executeandlog () -{ - echo "[\$@]" - eval \$@ -} - -help () -{ - echo "" - echo "Usage: pubtable_$DOCKER_TAG [options]" - echo "" - echo " pubtable_$DOCKER_TAG open [image] - open a pub table." - echo " pubtable_$DOCKER_TAG help - display this message." - echo "" - echo "Optionally supply an Docker image name to the open command." - echo "" -} - -# open a pub table. Only argument is the Docker image. -open() -{ - IMAGE="\$1" - COMMAND="docker create -ti \\ - -e HOST_UID=\$(id -u \$USER) \\ - -e HOST_GID=\$(id -g \$USER) \\ - -v \$SHARED_DIR_HOST:\$SHARED_DIR_CONTAINER \\ - --name dumuxpub_$DOCKER_TAG \\ - \$IMAGE /bin/bash" - - CONTAINER_NAME=\$(executeandlog \$COMMAND | tail -n 1) - executeandlog docker start -a -i \$CONTAINER_NAME - executeandlog docker rm \$CONTAINER_NAME -} - -# Check if user specified valid command otherwise print help message -if [ "\$1" == "open" ]; then - IMAGE="\$2" : \${IMAGE:="\$PUB_IMAGE_NAME"} - open \$IMAGE -else - help - exit 1 -fi - -EOT - -echo "--> Created pubtable_$DOCKER_TAG script to spin up the docker container." - - -touch Dockerfile -cat <> Dockerfile -# $MODULE_NAME docker container -# see https://github.com/phusion/baseimage-docker for information on the base image -# It is Ubuntu LTS customized for better Docker compatibility -FROM phusion/baseimage:0.9.22 -MAINTAINER $MODULE_MAINTAINER - -# run Ubuntu update as advised on https://github.com/phusion/baseimage-docker -RUN apt-get update \\ - && apt-get upgrade -y -o Dpkg::Options::="--force-confold" \\ - && apt-get clean \\ - && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* - -# install the basic dependencies -RUN apt-get update \\ - && apt-get install --no-install-recommends --yes \\ - ca-certificates \\ - vim \\ - python-dev \\ - python-pip \\ - git \\ - pkg-config \\ - build-essential \\ - gfortran \\ - cmake \\ - mpi-default-bin \\ - mpi-default-dev \\ - libsuitesparse-dev \\ - libsuperlu-dev \\ - libeigen3-dev \\ - doxygen \\ - && apt-get clean \\ - && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* - -# add the permission helper script to the my_init service -COPY ./docker/setpermissions.sh /etc/my_init.d/setpermissions.sh - -# create a dumux user -# add the welcome message (copied further down) output to bashrc -# make the set permission helper script executable -# add user to video group which enables graphics if desired -RUN useradd -m --home-dir /dumux dumux \\ - && echo "cat /dumux/WELCOME" >> /dumux/.bashrc \\ - && chmod +x /etc/my_init.d/setpermissions.sh \\ - && usermod -a -G video dumux - -# Turn off verbose syslog messages as described here: -# https://github.com/phusion/baseimage-docker/issues/186 -RUN touch /etc/service/syslog-forwarder/down - -# copy the extracted dumux-pub module and make dumux own it -COPY . /dumux/$MODULE_NAME -RUN chown -R dumux:dumux /dumux/$MODULE_NAME - -# switch to the dumux user and set the working directory -USER dumux -WORKDIR /dumux - -# create a shared volume communicating with the host -RUN mkdir /dumux/shared -VOLUME /dumux/shared - -# This is the message printed on entry -COPY ./docker/WELCOME /dumux/WELCOME - -# install dumux-pub module dependencies -COPY $INSTALL_DEP_SCRIPT /dumux/$INSTALL_DEP_SCRIPT -RUN ./$INSTALL_DEP_SCRIPT && rm -f /dumux/$INSTALL_DEP_SCRIPT - -# configure module -RUN /dumux/dune-common/bin/dunecontrol --opts=/dumux/dumux/optim.opts all - -# build doxygen documentation and tests -# all applications that use dune_add_test will be built like this -RUN cd $MODULE_NAME/build-cmake && make doc && make -j4 build_tests - -# switch back to root -USER root - -# set entry point like advised https://github.com/phusion/baseimage-docker -# this sets the permissions right, see above -ENTRYPOINT ["/sbin/my_init","--quiet","--","/sbin/setuser","dumux","/bin/bash","-l","-c"] - -# start interactive shell -CMD ["/bin/bash","-i"] - -EOT - -echo "--> Created Dockerfile. You can adapt it to your needs, or" - -echo "" -read -p " build the Docker image directly? [y/N]" BUILD -echo "" -if test x$BUILD = xy -o x$BUILD = xY; then - echo "Building Docker image... this may take several minutes." - cd .. - docker build -f docker/Dockerfile -t $DOCKER_TAG . - echo "" - echo "Successfully built docker image: $DOCKER_TAG. Have a look at docker/README.md." - echo "Check the container running docker run -it $DOCKER_TAG /bin/bash " - echo "in the same directory as the Dockerfile." - echo "And try using the convenience script pubtable_$DOCKER_TAG, see docker/README.md." -else - cd .. - echo "You can build your Docker image later by running docker build -f docker/Dockerfile -t $DOCKER_TAG ." - echo "in your module directory, i.e. above the docker folder containing Dockerfile." -fi diff --git a/bin/moduleutil/extractmodulepart.sh b/bin/moduleutil/extractmodulepart.sh deleted file mode 100755 index 9471bdd4cbac77a3e78795d81f097dc5f4f2ccc4..0000000000000000000000000000000000000000 --- a/bin/moduleutil/extractmodulepart.sh +++ /dev/null @@ -1,422 +0,0 @@ -#! /bin/bash - -# check if help is needed -if test "$1" = "--help" || test "$1" = "-help" \ - || test "$1" = "help" || test "$1" = ""; then - echo "" - echo "USAGE: $0 MODULE_DIR FOLDER_1 [FOLDER_2 ...]" - echo "" - echo "MODULE_DIR is the folder containing the DUNE module from which you" - echo "want to extract. The script has to be called one level above it." - echo "" - echo "The FOLDERs need to indicate subfolders of MODULE_DIR. At least one" - echo "of them has to contain a source file *.cc of an executable for which" - echo "you would like to timber a table in dumux-pub." - exit 0 -fi - -MODULE_DIR=$1 -# if MODULE_DIR contains a slash as last character, delete it -MODULE_DIR=$(echo $MODULE_DIR | sed s'/\/$//') -# check if we are above MODULE_DIR -if (! [ -d $MODULE_DIR ]); then - echo "ERROR: you need to run the script one level above the folder $MODULE_DIR." - echo "Run \"$0 --help\" for details." - exit 1 -fi - -# determine all source files in the paths passed as arguments -cd $MODULE_DIR -MODULE_FULL_PATH=$(pwd) -ALL_SOURCES="" -ALL_DIRECTORIES="" -for DIR_PATH in ${*:2}; do - STRIPPED_PATH=$(sed 's%.*'"$MODULE_DIR"'/%%g' <(echo "$DIR_PATH")) - ALL_DIRECTORIES="$ALL_DIRECTORIES $STRIPPED_PATH" - ALL_SOURCES="$ALL_SOURCES $(find $STRIPPED_PATH -name '*.cc' 2>/dev/null)" -done -cd .. - -# check if sources have been obtained -CONTRACTED="$(echo "$ALL_SOURCES" | tr -d " \t\n\r")" -if test "$CONTRACTED" = ""; then - echo "ERROR: no source files *.cc found in the directories ${*:2}." - echo "Be sure to provide a list of paths as arguments to this script." - echo "Run \"$0 --help\" for details." - exit 1; -fi - -# try to find the duneproject script -if hash duneproject 2>/dev/null; then - DUNE_PROJECT="duneproject" -else - DUNE_PROJECT=$(find . -name 'duneproject') -fi -if test "$DUNE_PROJECT" = ""; then - echo "ERROR: Could not find duneproject." - echo "Be sure to either have duneproject in your search path" - echo "or to run this script from a directory that contains duneproject." - exit 1; -fi - -# give explanations -echo "" -echo "This script will" -echo "- extract the following sub-folders of $MODULE_DIR:" -echo "" -for DIR_PATH in $ALL_DIRECTORIES; do - echo " $DIR_PATH," -done -echo "" -echo " and all headers in $MODULE_DIR that are required to build the" -echo " executables from the sources" -echo "" -for SOURCE in $ALL_SOURCES; do - echo " $SOURCE," -done -echo "" -echo "- copy the extracted files into a freshly created DUNE module, retaining the" -echo " directory structure," -echo "" -echo "- update/create all required files like CMakeLists.txt," -echo "" -echo "- store the versions of all used Dune module" -echo "" -echo "- and extract their modifications as patches." -echo "" -echo "Thus, you receive a fully-working DUNE module containing the subset of" -echo "$MODULE_DIR that is required to run your application." -echo "" -echo "duneproject will be run now. The new module should NOT depend on the" -echo "module in $MODULE_DIR." -echo "" -read -p "Read the above and press [Enter] to proceed..." - -# run duneproject -OLD_LS="$(ls)" -$DUNE_PROJECT -NEW_LS="$(ls)" - -# determine the new module/directory name -DIFF_OUTPUT=$(diff <(echo "$OLD_LS" ) <(echo "$NEW_LS")) -FOUND="0" -MODULE_NAME="" -for WORD in $DIFF_OUTPUT; do - if test "$FOUND" = "1"; then - MODULE_NAME=$WORD - fi - if test "$WORD" = ">"; then - FOUND="1" - fi -done -if test "$MODULE_NAME" = ""; then - echo "ERROR: could not find new module. Aborting." - exit 1 -else - echo "" - echo "$(basename $0): Found new module $MODULE_NAME" -fi - -echo -n "Determining required headers..." -cd $MODULE_DIR - -# initialize lists to hold required headers -LAST_REQUIRED_HEADERS="" -REQUIRED_HEADERS="$ALL_SOURCES" - -while test "$LAST_REQUIRED_HEADERS" != "$REQUIRED_HEADERS"; do - echo -n "." - LAST_REQUIRED_HEADERS="$REQUIRED_HEADERS" - - # remove the file that stores all required headers line by line - rm -f tmp_header_file - - for HEADER in $REQUIRED_HEADERS; do - # if tmp_header_file does not exist, create it - if test "$(ls tmp_header_file 2>/dev/null)" = ""; then - touch tmp_header_file - fi - - # append header name to tmp_header_file - echo "$HEADER" >> tmp_header_file - - # obtain the base name and the directory name of the header that is considered - HEADER_BASE_NAME=$(basename $HEADER) - HEADER_DIR_NAME=$(dirname $HEADER) - - # create a list of all files that are included from the header - sed -i 's/#include/#include /' $HEADER - INCLUDE_LIST=$(tr -s " " < $HEADER | tr -d '><"' | awk '/#include/{print $2}') - sed -i 's/#include /#include/' $HEADER - - # look at each of the included files - for INCLUDED_HEADER in $INCLUDE_LIST; do - # don't include config.h - if test "$INCLUDED_HEADER" = "config.h"; then - continue - fi - - INCLUDED_BASE_NAME=$(basename $INCLUDED_HEADER) - INCLUDED_DIR_NAME=$(dirname $INCLUDED_HEADER) - - # if the header file exists, add it - if test "$(ls $INCLUDED_HEADER 2>/dev/null)" = "$INCLUDED_HEADER"; then - echo "$INCLUDED_HEADER" >> tmp_header_file - continue - fi - - # try the header preceded by its path - INCLUDED_HEADER_WITH_PATH="${HEADER_DIR_NAME}/${INCLUDED_HEADER}" - - # if the header file actually exists, add it - if test "$(ls $INCLUDED_HEADER_WITH_PATH 2>/dev/null)" = "$INCLUDED_HEADER_WITH_PATH"; then - # remove "../" from the path - cd $(dirname $INCLUDED_HEADER_WITH_PATH) - HEADER_FULL_PATH=$(pwd) - HEADER_RELATIVE_PATH=${HEADER_FULL_PATH#$MODULE_FULL_PATH} - HEADER_RELATIVE_PATH=$(echo $HEADER_RELATIVE_PATH | sed 's/^.//') - INCLUDED_HEADER_WITH_PATH="${HEADER_RELATIVE_PATH}/${INCLUDED_BASE_NAME}" - cd $MODULE_FULL_PATH - echo "$INCLUDED_HEADER_WITH_PATH" >> tmp_header_file - fi - done - done - - # sort the required headers, eliminate copies - REQUIRED_HEADERS=$(sort -u tmp_header_file) -done - -# remove the file that stores all required headers line by line -rm -f tmp_header_file - -# provide some output and copy everything to the new module -echo "" -echo -n "Number of required headers: " -echo "$REQUIRED_HEADERS" | wc -w -for HEADER in $REQUIRED_HEADERS; do - echo $HEADER - rsync -R $HEADER ../$MODULE_NAME -done -for DIR_PATH in $ALL_DIRECTORIES; do - rsync -rR $DIR_PATH ../$MODULE_NAME -done - -# delete all architecture-dependent files -cd ../$MODULE_NAME -find . -name Makefile.in -delete -find . -name Makefile -delete -find . -name '*.o' -delete -find . -wholename '*.deps/*' -delete -find . -path '*.deps' -delete -echo "Removed architecture-dependent files." - -# remove directories that are not required -sed -i '/"dune"/d' CMakeLists.txt -sed -i '/"src"/d' CMakeLists.txt -sed -i '/"m4"/d' CMakeLists.txt -rm -rf dune/ -rm -rf src/ -rm -rf m4/ - -# create a list of the subfolders -EMPTY_DIR_NAME="." -rm -f tmp_subdir_file -for HEADER in $REQUIRED_HEADERS; do - - # move through every header, cutting off the last folder - while test "$HEADER" != $EMPTY_DIR_NAME; do - if test "$(dirname $HEADER)" != $EMPTY_DIR_NAME; then - dirname $HEADER >> tmp_subdir_file - fi - - HEADER=$(dirname $HEADER) - done - - # finally add the topmost folder - if test "$(basename $HEADER)" != $EMPTY_DIR_NAME; then - basename $HEADER >> tmp_subdir_file - fi -done -SUBDIR_LIST=$(sort -u tmp_subdir_file) -rm -f tmp_subdir_file - -# treat every subfolder -START_DIR=$PWD -INITIAL_SUBDIR_LIST="" -for SUBDIR in $SUBDIR_LIST; do - if test "$SUBDIR" = "$(basename $SUBDIR)"; then - INITIAL_SUBDIR_LIST="$INITIAL_SUBDIR_LIST $SUBDIR" - fi - - cd $SUBDIR - - # create lists of files and folders - FILE_LIST="" - DIR_LIST="" - for FILE_OR_FOLDER in $( ls ); do - if ([ -f $FILE_OR_FOLDER ]); then - FILE_LIST="$FILE_LIST $FILE_OR_FOLDER" - fi - - if ([ -d $FILE_OR_FOLDER ]); then - DIR_LIST="$DIR_LIST $FILE_OR_FOLDER" - fi - done - - # create CMakeLists.txt if not present - if ([ ! -f CMakeLists.txt ]); then - # add subfolder information - for DIR in $DIR_LIST; do - echo "add_subdirectory(\"$DIR\")" >> CMakeLists.txt - done - - # determine whether to add file information - ADD_FILE_INFO="0" - for FILE in $FILE_LIST; do - if ([ -f $FILE ]); then - ADD_FILE_INFO="1" - fi - done - - # add file information - if test "$ADD_FILE_INFO" = "1"; then - echo "" >> CMakeLists.txt - echo "install(FILES" >> CMakeLists.txt - - for FILE in $FILE_LIST; do - echo " $FILE" >> CMakeLists.txt - done - - echo " DESTINATION \${CMAKE_INSTALL_INCLUDEDIR}/$SUBDIR)" >> CMakeLists.txt - fi - fi - - cd $START_DIR - -done - -# update top CMakeLists.txt -for INITIAL_SUBDIR in $INITIAL_SUBDIR_LIST; do - sed -i '/add_subdirectory("doc")/a add_subdirectory('"$INITIAL_SUBDIR"')' CMakeLists.txt -done -echo "Updated and created CMakeLists.txt's." -cd .. - -# add includes to the automatically generated file *Macros.cmake -MACROS_FILE="$(find $MODULE_NAME -name '*Macros.cmake')" -if test "$(find $MODULE_NAME -type f -name 'CMakeLists.txt' -exec grep add_csv_file_links {} \; 2>/dev/null)" != ""; then - cp dumux-devel/cmake/modules/AddCSVFileLinks.cmake $MODULE_NAME/cmake/modules/. - echo "include(AddCSVFileLinks)" >>$MACROS_FILE -fi -if test "$(find $MODULE_NAME -type f -name 'CMakeLists.txt' -exec grep add_executable_all {} \; 2>/dev/null)" != ""; then - cp dumux-devel/cmake/modules/AddExecutableAll.cmake $MODULE_NAME/cmake/modules/. - echo "include(AddExecutableAll)" >>$MACROS_FILE -fi -if test "$(find $MODULE_NAME -type f -name 'CMakeLists.txt' -exec grep add_file_link {} \; 2>/dev/null)" != ""; then - cp dumux-devel/cmake/modules/AddFileLink.cmake $MODULE_NAME/cmake/modules/. - echo "include(AddFileLink)" >>$MACROS_FILE -fi -if test "$(find $MODULE_NAME -type f -name 'CMakeLists.txt' -exec grep add_folder_link {} \; 2>/dev/null)" != ""; then - cp dumux-devel/cmake/modules/AddFolderLink.cmake $MODULE_NAME/cmake/modules/. - echo "include(AddFolderLink)" >>$MACROS_FILE -fi -if test "$(find $MODULE_NAME -type f -name 'CMakeLists.txt' -exec grep add_gnuplot_file_links {} \; 2>/dev/null)" != ""; then - cp dumux-devel/cmake/modules/AddGnuplotFileLinks.cmake $MODULE_NAME/cmake/modules/. - echo "include(AddGnuplotFileLinks)" >>$MACROS_FILE -fi - -# create $README_FILE -README_FILE="README.md" -mv $MODULE_NAME/README $MODULE_NAME/$README_FILE -echo "This file has been created automatically. Please adapt it to your needs." >$MODULE_NAME/$README_FILE -echo "" >>$MODULE_NAME/$README_FILE -echo "===============================" >>$MODULE_NAME/$README_FILE -echo "" >>$MODULE_NAME/$README_FILE -echo "The content of this DUNE module was extracted from the module $MODULE_DIR." >>$MODULE_NAME/$README_FILE -echo "In particular, the following subfolders of $MODULE_DIR have been extracted:" >>$MODULE_NAME/$README_FILE -echo "" >>$MODULE_NAME/$README_FILE -for DIR_PATH in $ALL_DIRECTORIES; do - echo " $DIR_PATH," >>$MODULE_NAME/$README_FILE -done -echo "" >>$MODULE_NAME/$README_FILE -echo "Additionally, all headers in $MODULE_DIR that are required to build the" >>$MODULE_NAME/$README_FILE -echo "executables from the sources" >>$MODULE_NAME/$README_FILE -echo "" >>$MODULE_NAME/$README_FILE -for SOURCE in $ALL_SOURCES; do - echo " $SOURCE," >>$MODULE_NAME/$README_FILE -done -echo "" >>$MODULE_NAME/$README_FILE -echo "have been extracted. You can build the module just like any other DUNE" >>$MODULE_NAME/$README_FILE -echo "module. For building and running the executables, please go to the folders" >>$MODULE_NAME/$README_FILE -echo "containing the sources listed above." >>$MODULE_NAME/$README_FILE -echo "" >>$MODULE_NAME/$README_FILE -echo "" >>$MODULE_NAME/$README_FILE -echo "" >>$MODULE_NAME/$README_FILE -echo "" >>$MODULE_NAME/$README_FILE - -# get versions from modules we are depeding on -# create patches for un-pushed commits and uncomitted changes - -# try to find the dunecontrol script -if hash dunecontrol 2>/dev/null; then - DUNE_CONTROL="dunecontrol" -else - DUNE_CONTROL=$(find . -type f -executable -name 'dunecontrol') -fi -if test "$DUNE_CONTROL" = ""; then - echo "ERROR: Could not find dunecontrol." - echo "Be sure to either have dunecontrol in your search path" - echo "or to run this script from a directory that contains dunecontrol." - exit -fi -# get names of all modules we are depeding on -echo "Extracting dependencies to other Dune modules" -DEPENDING_MODULE_NAMES=$($DUNE_CONTROL --module=$MODULE_NAME 2>/dev/null | head -n 1) -DEPENDING_MODULE_NAMES=$(sed 's/--- going to build //' <<< "$DEPENDING_MODULE_NAMES") -DEPENDING_MODULE_NAMES=$(sed 's/ ---//' <<< "$DEPENDING_MODULE_NAMES") -# load script -CALL_FROM_EXTERNAL_SCRIPT="yes" -SCRIPT_DIR="${BASH_SOURCE%/*}" -if [[ ! -d "$SCRIPT_DIR" ]]; then - SCRIPT_DIR="$PWD"; -fi -# create install script -touch $MODULE_NAME/install$MODULE_NAME.sh -. "$SCRIPT_DIR/getusedversions.sh" -# execute function from script -echo "Extracting Git status of dependencies and creating patches" -for MOD in $DEPENDING_MODULE_NAMES -do - if [ $MOD != $MODULE_NAME ]; then - MODULE_DIR=${MOD%*/} - getVersionGit $MODULE_DIR $(pwd)/$MODULE_NAME/install$MODULE_NAME.sh | tee -a $MODULE_NAME/$README_FILE - grep "Error:" $MODULE_NAME/$README_FILE > /dev/null - EXIT_CODE=$? - if [[ $EXIT_CODE == 0 ]]; then - exit - fi - fi -done - -# move patches folder into module if existing -if [[ -d patches ]]; then - mv patches $MODULE_NAME -fi - -# output guidence for users -echo "" -echo "*************************************************************************" -echo "The extracted module is contained in the subfolder \"$MODULE_NAME\"." -echo "You can build it using \"dunecontrol ... --only=$MODULE_NAME all\"." -echo "*************************************************************************" -echo "BEFORE building, you can add the module to dumux-pub by something like:" -echo "(Rename module name if it does not match the AuthorLastNameYearx scheme" -echo "and commit it to the Git repository dumux-pub)" -echo "git clone https://git.iws.uni-stuttgart.de/dumux-pub/AuthorLastNameYearx.git" -echo "sed -i '/Module:/c\Module: AuthorLastNameYearx' $MODULE_NAME/dune.module" -echo "mv $MODULE_NAME/* dumux-pub/AuthorLastNameYearx/." -echo "cd AuthorLastNameYearx" -echo "git commit -a" -echo "git push" - -exit 0 diff --git a/bin/moduleutil/getusedversions.sh b/bin/moduleutil/getusedversions.sh deleted file mode 100755 index 102e2f0eed1d3eb3c00f69702232f9736162d1af..0000000000000000000000000000000000000000 --- a/bin/moduleutil/getusedversions.sh +++ /dev/null @@ -1,105 +0,0 @@ -# !/bin/bash - -# skript to extract Git version information -# including automating patch extraction and handling of uncommitted changes -# -# (c) 2016 Thomas Fetzer -# (c) 2016 Christoph Grüninger -# - -if [ "$1" = "-h" ]; then - echo "USAGE: ./getDumuxDuneVersions.sh" - echo; exit -fi - -OUTFILE=versionNumbers.txt - -# create patches from get local commits -# $1 directory /which is local copy of Git repository to check, assumed to be identical with module name -# $2 script file to append command for checking out Git repository -function getPatchesGit -{ - # if not yet existing, create common patch directory - if [ ! -d ../patches ]; then - mkdir ../patches - fi - # create directory for patches of module - mkdir ../patches-$1 - - # create patch for local commits - git format-patch --output-directory ../patches-$1 @{upstream} - # create extra patch for uncommitted changes if necessary - if [[ `git status --porcelain | grep -v "build.*"` ]]; then - git diff > ../patches-$1/9999-uncommitted-changes.patch - fi - - # move and rename all patches to common patch directory - MODULE_PWD=$PWD - cd ../patches-$1 ; - for file in *.patch - do - mv $file ../patches/$1_$file - printf "Created patch %s\n" $1_$file - echo "patch -p1 < ../patches/$1_$file" >> $2 - done - cd $MODULE_PWD - # remove helper dirctory - rm -r ../patches-$1 -} - -# get version from Git, output and write to file -# $1 directory which is local copy of Git repository to check, assumed to be identical with module name -# $2 script file to append command for checking out Git repository -function getVersionGit -{ - # enter directory - cd $1 - # get URL from remote a.k.a. the repository - GIT_REMOTE="$(git ls-remote --get-url)" - # get revision, date, author and branch of last remote/upstream commit - GIT_UPSTREAM_REVISION="$(git log -n 1 --format=%H @{upstream})" - GIT_UPSTREAM_DATE="$(git log -n 1 --format=%ai @{upstream})" - GIT_UPSTREAM_AUTHOR="$(git log -n 1 --format=%an @{upstream})" - GIT_UPSTREAM_BRANCH="$(git rev-parse --abbrev-ref HEAD)" - printf "%-25s %-15s %-15s\n" $1 $GIT_UPSTREAM_BRANCH $GIT_UPSTREAM_REVISION - echo "# $1" >> $2 - echo "# $GIT_UPSTREAM_BRANCH # $GIT_UPSTREAM_REVISION # $GIT_UPSTREAM_DATE # $GIT_UPSTREAM_AUTHOR" >> $2 - echo "git clone $GIT_REMOTE" >> $2 - echo "cd $1" >> $2 - echo "git checkout $GIT_UPSTREAM_BRANCH" >> $2 - echo "git reset --hard $GIT_UPSTREAM_REVISION" >> $2 - # check for untracked files and error out if found, but ignore build* - if [[ `git ls-files --others --exclude-standard | grep -v "build*" | grep -v "\.[A-Za-z]*"` ]]; then - echo "Error: Found untracked files in module $1. Please commit, stash or remove them." - echo "You might want to delete the folder patches/ and the module just created." - exit - fi - # create patches if number of commits is not zero - if [[ "$(git rev-list HEAD ^@{upstream} --count)" > 0 ]] || [[ `git status --porcelain | grep -v "build.*" | grep -v "\.[A-Za-z]*"` ]]; then - getPatchesGit $1 $2 - fi - echo "cd .." >> $2 - echo "" >> $2 - cd .. -} - -# run script from command line -# suppressed for use of external script when variable set accordingly -if [ "$CALL_FROM_EXTERNAL_SCRIPT" != "yes" ]; then - echo "# DUNE/DUMUX VERSIONS" > $OUTFILE - - echo "Creating file containing the version numbers:" - for dir in dune-* dumux* - do - DIR=${dir%*/} - # echo $DIR - # skip folders that are no Git repository - if [ -d $DIR/.git ]; then - getVersionGit $DIR ../$OUTFILE - fi - done - - echo "done" - - exit -fi diff --git a/bin/testing/fuzzycomparedata.py b/bin/testing/fuzzycomparedata.py index 6d16947e04fcd04bf4880a5e57bf7216e4465e9c..01b3e1e8266252e28e752a2f992d9e8bce0f4ab6 100644 --- a/bin/testing/fuzzycomparedata.py +++ b/bin/testing/fuzzycomparedata.py @@ -42,8 +42,8 @@ def compare_data(dataFile1, dataFile2, delimiter, absolute=1.5e-7, relative=1e-2 print("... with a maximum relative error of {} and a maximum absolute error of {}*max_abs_parameter_value.".format(relative, absolute)) # construct element tree from data files - data1 = list(csv.reader(open(dataFile1, 'rb'), delimiter=delimiter)) - data2 = list(csv.reader(open(dataFile2, 'rb'), delimiter=delimiter)) + data1 = list(csv.reader(open(dataFile1, 'r'), delimiter=delimiter)) + data2 = list(csv.reader(open(dataFile2, 'r'), delimiter=delimiter)) if (len(data1) != len(data2)): print("Length of data1 and data2 not equal: ref=", len(data1), ",new=", len(data2), ". Aborting!") diff --git a/bin/testing/fuzzycomparevtu.py b/bin/testing/fuzzycomparevtu.py index 0d09c869b6105fd545d067b66a663a531ee910ce..830e37434b69deece18cd683a274b809240bd8cf 100644 --- a/bin/testing/fuzzycomparevtu.py +++ b/bin/testing/fuzzycomparevtu.py @@ -15,7 +15,9 @@ import sys import math from six.moves import range from six.moves import zip - +import os +import re +import glob # fuzzy compare VTK tree from VTK strings def compare_vtk(vtk1, vtk2, absolute=1.5e-7, relative=1e-2, zeroValueThreshold={}, verbose=True): @@ -24,7 +26,11 @@ def compare_vtk(vtk1, vtk2, absolute=1.5e-7, relative=1e-2, zeroValueThreshold={ Arguments: ---------- vtk1, vtk2 : string - The filenames of the vtk files to compare + The filenames of the vtk files to compare. If a pvd file is given + instead, the corresponding possibly parallel vtk file(s) have to be + present and will be converted to a (series of) sequential vtk file(s). + The last one in the natural ordering of these files will be taken for + comparison. Keyword Arguments: ------------------ @@ -45,6 +51,15 @@ def compare_vtk(vtk1, vtk2, absolute=1.5e-7, relative=1e-2, zeroValueThreshold={ root1 = ET.fromstring(open(vtk1).read()) root2 = ET.fromstring(open(vtk2).read()) + # convert parallel vtu to sequential vtu if necessary + convertedFromParallelVtu = False + if vtk1.endswith('.pvtu'): + root1 = convert_pvtu_to_vtu(root1, vtk1) + convertedFromParallelVtu = True + if vtk2.endswith('.pvtu'): + root2 = convert_pvtu_to_vtu(root2, vtk2) + convertedFromParallelVtu = True + # sort the vtk file in case nodes appear in different positions # e.g. because of minor changes in the output code sortedroot1 = sort_vtk(root1) @@ -56,17 +71,106 @@ def compare_vtk(vtk1, vtk2, absolute=1.5e-7, relative=1e-2, zeroValueThreshold={ # sort the vtk file so that the comparison is independent of the # index numbering (coming e.g. from different grid managers) - sortedroot1, sortedroot2 = sort_vtk_by_coordinates(sortedroot1, sortedroot2, verbose) + sortedroot1, sortedroot2 = sort_vtk_by_coordinates(sortedroot1, sortedroot2, verbose, convertedFromParallelVtu) # do the fuzzy compare - if is_fuzzy_equal_node(sortedroot1, sortedroot2, absolute, relative, zeroValueThreshold, verbose): + if is_fuzzy_equal_node(sortedroot1, sortedroot2, absolute, relative, zeroValueThreshold, verbose, convertedFromParallelVtu): return 0 else: return 1 +# convert a parallel vtu file into sequential one by glueing the pieces together +def convert_pvtu_to_vtu(pvturoot, filename): + + # get the directory of the vtu file in case the piece paths are relative + dirname = os.path.dirname(os.path.abspath(filename)) + # get the piece file names from the parallel vtu + pieces = [] + for piece in pvturoot.findall(".//Piece"): + piecename = os.path.join(dirname, os.path.basename(piece.attrib["Source"])) + pieces.append(ET.fromstring(open(piecename).read())) + + root = pieces[0] + rootCellDataArrays = [] + rootPointDataArrays = [] + + for dataArray in root.findall(".//PointData/DataArray"): + rootPointDataArrays.append(dataArray) + for dataArray in root.findall(".//CellData/DataArray"): + rootCellDataArrays.append(dataArray) + for dataArray in root.findall(".//DataArray"): + if dataArray.attrib["Name"] == "connectivity": + rootConnectivity = dataArray + if dataArray.attrib["Name"] == "types": + rootTypes = dataArray + if dataArray.attrib["Name"] == "offsets": + rootOffsets = dataArray + if dataArray.attrib["Name"] == "Coordinates": + rootCoordinates = dataArray + + # add all pieces to the first piece + for piece in pieces[1:]: + cellDataArrays = [] + pointDataArrays = [] + for dataArray in piece.findall(".//PointData/DataArray"): + pointDataArrays.append(dataArray) + for dataArray in piece.findall(".//CellData/DataArray"): + cellDataArrays.append(dataArray) + for dataArray in piece.findall(".//DataArray"): + if dataArray.attrib["Name"] == "connectivity": + connectivity = dataArray + if dataArray.attrib["Name"] == "types": + types = dataArray + if dataArray.attrib["Name"] == "offsets": + offsets = dataArray + if dataArray.attrib["Name"] == "Coordinates": + coordinates = dataArray + + # compute offset for the offsets vector (it's the last entry of the current root piece) + for dataArray in root.findall(".//Cells/DataArray"): + if dataArray.attrib["Name"] == "offsets": + offsets_offset = int(dataArray.text.strip().rsplit(' ', 1)[1]) + + # add the offsets to the root piece + for value in offsets.text.strip().split(): + newvalue = " " + str(int(value) + offsets_offset) + " " + rootOffsets.text += newvalue + + # compute offset for the connectivity vector (it's the number of points of the current root piece) + rootNumPoints = int(root.findall(".//Piece")[0].attrib["NumberOfPoints"]) + rootNumCells = int(root.findall(".//Piece")[0].attrib["NumberOfCells"]) + + # add the connectivity vector to the root piece + for value in connectivity.text.strip().split(): + newvalue = " " + str(int(value) + rootNumPoints) + " " + rootConnectivity.text += newvalue + + # add the types and coordinates + rootTypes.text += " " + types.text + rootCoordinates.text += " " + coordinates.text + + # add all the data arrays + for i, dataArray in enumerate(cellDataArrays): + rootCellDataArrays[i].text += " " + cellDataArrays[i].text + for i, dataArray in enumerate(pointDataArrays): + rootPointDataArrays[i].text += " " + pointDataArrays[i].text + + # update the number of cells and points + newNumPoints = int(piece.findall(".//Piece")[0].attrib["NumberOfPoints"]) + rootNumPoints + newNumCells = int(piece.findall(".//Piece")[0].attrib["NumberOfCells"]) + rootNumCells + + root.findall(".//Piece")[0].attrib["NumberOfPoints"] = str(newNumPoints) + root.findall(".//Piece")[0].attrib["NumberOfCells"] = str(newNumCells) + + # for debugging the merged vtu file can be written out and viewed in paraview + # testname = os.path.join(dirname, "comparisontemp-" + os.path.basename(pvturoot.findall(".//Piece")[0].attrib["Source"])) + # vtu = ET.ElementTree(root) + # vtu.write(testname) + + return root # fuzzy compare of VTK nodes -def is_fuzzy_equal_node(node1, node2, absolute, relative, zeroValueThreshold, verbose): +def is_fuzzy_equal_node(node1, node2, absolute, relative, zeroValueThreshold, verbose, convertedFromParallelVtu=False): is_equal = True for node1child, node2child in zip(node1.iter(), node2.iter()): @@ -76,9 +180,11 @@ def is_fuzzy_equal_node(node1, node2, absolute, relative, zeroValueThreshold, ve is_equal = False else: return False - if list(node1.attrib.items()) != list(node2.attrib.items()): + if not convertedFromParallelVtu and list(node1.attrib.items()) != list(node2.attrib.items()): if verbose: print('Attributes differ in node: {}'.format(node1.tag)) + print('Attributes1: ', list(node1.attrib.items())) + print('Attributes2: ', list(node2.attrib.items())) is_equal = False else: return False @@ -89,9 +195,13 @@ def is_fuzzy_equal_node(node1, node2, absolute, relative, zeroValueThreshold, ve else: return False if node1child.text or node2child.text: + if node1child.get("NumberOfComponents") == None: + numberOfComponents = 1 + else: + numberOfComponents = int(node1child.attrib["NumberOfComponents"]) if not is_fuzzy_equal_text(node1child.text, node2child.text, node1child.attrib["Name"], - int(node1child.attrib["NumberOfComponents"]), + numberOfComponents, absolute, relative, zeroValueThreshold, verbose): if node1child.attrib["Name"] == node2child.attrib["Name"]: if verbose: @@ -253,10 +363,9 @@ def sort_vtk(root): # return the sorted element tree return newroot - # sorts the data by point coordinates so that it is independent of index numbering -def sort_vtk_by_coordinates(root1, root2, verbose): - if not is_fuzzy_equal_node(root1.find(".//Points/DataArray"), root2.find(".//Points/DataArray"), absolute=1e-2, relative=1.5e-7, zeroValueThreshold=dict(), verbose=False): +def sort_vtk_by_coordinates(root1, root2, verbose, convertedFromParallelVtu=False): + if not is_fuzzy_equal_node(root1.find(".//Points/DataArray"), root2.find(".//Points/DataArray"), absolute=1e-2, relative=1.5e-7, zeroValueThreshold=dict(), verbose=True, convertedFromParallelVtu=False): if verbose: print("Sorting vtu by coordinates...") for root in [root1, root2]: @@ -271,23 +380,31 @@ def sort_vtk_by_coordinates(root1, root2, verbose): cellDataArrays.append(dataArray.attrib["Name"]) for dataArray in root.findall(".//DataArray"): dataArrays[dataArray.attrib["Name"]] = dataArray.text - numberOfComponents[dataArray.attrib["Name"]] = dataArray.attrib["NumberOfComponents"] + if dataArray.get("NumberOfComponents") == None: + numberOfComponents[dataArray.attrib["Name"]] = 1 + else: + numberOfComponents[dataArray.attrib["Name"]] = dataArray.attrib["NumberOfComponents"] vertexArray = [] coords = dataArrays["Coordinates"].split() # group the coordinates into coordinate tuples dim = int(numberOfComponents["Coordinates"]) - for i in range(len(coords) // dim): - vertexArray.append([float(c) for c in coords[i * dim: i * dim + dim]]) - # obtain a vertex index map - vMap = [] - for idx, coords in enumerate(vertexArray): - vMap.append((idx, coords)) - sortedVMap = sorted(vMap, key=itemgetter(1)) - vertexIndexMap = {} - for idxNew, idxOld in enumerate(sortedVMap): - vertexIndexMap[idxOld[0]] = idxNew + # If the vtk file has been converted from pvd, vertices may be + # duplicated. The following procedure eliminates the duplications. + if convertedFromParallelVtu: + uniqueIdx = [] + for i in range(len(coords) // dim): + pos = [float(c) for c in coords[i * dim : i * dim + dim]] + if pos in vertexArray: + uIdx = vertexArray.index(pos) + else: + uIdx = len(vertexArray) + vertexArray.append(pos) + uniqueIdx.append(uIdx) + else: + for i in range(len(coords) // dim): + vertexArray.append([float(c) for c in coords[i * dim : i * dim + dim]]) # group the cells into vertex index tuples cellArray = [] @@ -297,13 +414,45 @@ def sort_vtk_by_coordinates(root1, root2, verbose): for cellIdx, offset in enumerate(offsets): cellArray.append([]) for v in range(vertex, int(offset)): - cellArray[cellIdx].append(int(connectivity[v])) + if convertedFromParallelVtu: + cellArray[cellIdx].append(uniqueIdx[int(connectivity[v])]) + else: + cellArray[cellIdx].append(int(connectivity[v])) vertex += 1 + # for non-conforming output vertices can have the same coordinates and also + # different indices / sorting so we need another criterium to sort. + # we use the largest cell midpoint coordinate vector the vertex is connected to + largestCellMidPointForVertex = [[0, 0, 0]]*len(vertexArray) + for cellIdx, cell in enumerate(cellArray): + # compute cell midpoint + coords = [vertexArray[i] for i in cell] + midpoint = [i/float(len(coords)) for i in [sum(coord) for coord in zip(*coords)]] + for vertexIndex in cell: + largestCellMidPointForVertex[vertexIndex] = max(largestCellMidPointForVertex[vertexIndex], midpoint) + + # obtain a vertex index map + vMap = [] + for idx, coords in enumerate(vertexArray): + vMap.append((idx, coords)) + + vertexIndexMap = [0]*len(vMap) + vertexIndexMapInverse = [0]*len(vMap) + # first sort by coordinates, if the same by largestCellMidPointForVertex + for idxNew, idxOld in enumerate(sorted(vMap, key=lambda x: (x[1], largestCellMidPointForVertex[x[0]]))): + vertexIndexMap[idxOld[0]] = idxNew + vertexIndexMapInverse[idxNew] = idxOld[0] + # replace all vertex indices in the cellArray by the new indices - for cell in cellArray: - for idx, vertexIndex in enumerate(cell): - cell[idx] = vertexIndexMap[vertexIndex] + for i, cell in enumerate(cellArray): + for j, vertexIndex in enumerate(cell): + cellArray[i][j] = vertexIndexMap[vertexIndex] + + # sort the indices of all cells in case the two grids have different orientation of the elements + # this doesn't necessarily have to be a valid vtk order, it's just temporary for a sorted literal comparison + # of the files + for i, cell in enumerate(cellArray): + cellArray[i] = sorted(cell) # sort all data arrays for name, text in list(dataArrays.items()): @@ -317,7 +466,15 @@ def sort_vtk_by_coordinates(root1, root2, verbose): items = newitems # sort the items: we have either vertex or cell data if name in pointDataArrays: - sortedItems = [j for (i, j) in sorted(zip(vertexArray, items), key=itemgetter(0))] + # use the unique indices if the vtk file has been converted + # from pvd + if convertedFromParallelVtu: + uniqueItems = [None]*len(vertexArray) + for i in range(len(items)): + uniqueItems[uniqueIdx[i]] = items[i] + sortedItems = [uniqueItems[i] for i in vertexIndexMapInverse] + else: + sortedItems = [items[i] for i in vertexIndexMapInverse] elif name in cellDataArrays or name == "types": sortedItems = [j for (i, j) in sorted(zip(cellArray, items), key=itemgetter(0))] elif name == "offsets": @@ -327,7 +484,7 @@ def sort_vtk_by_coordinates(root1, root2, verbose): counter += len(cell) sortedItems.append([str(counter)]) elif name == "Coordinates": - sortedItems = sorted(vertexArray) + sortedItems = [vertexArray[i] for i in vertexIndexMapInverse] elif name == "connectivity": sortedItems = sorted(cellArray) @@ -350,13 +507,19 @@ if __name__ == "__main__": parser = argparse.ArgumentParser(description='Fuzzy compare of two VTK\ (Visualization Toolkit) files. The files are accepted if for every\ value the difference is below the absolute error or below the\ - relative error or below both.') + relative error or below both. If a pvd file is given instead, the\ + corresponding possibly parallel vtk file(s) have to be present and\ + will be converted to a (series of) sequential vtk file(s). The last\ + one in the natural ordering of these files will be taken for\ + comparison.') parser.add_argument('vtk_file_1', type=str, help='first file to compare') parser.add_argument('vtk_file_2', type=str, help='second file to compare') parser.add_argument('-r', '--relative', type=float, default=1e-2, help='maximum relative error (default=1e-2)') parser.add_argument('-a', '--absolute', type=float, default=1.5e-7, help='maximum absolute error (default=1.5e-7)') parser.add_argument('-z', '--zeroThreshold', type=json.loads, default='{}', help='Thresholds for treating numbers as zero for a parameter as a python dict e.g. {"vel":1e-7,"delP":1.0}') - parser.add_argument('-v', '--verbose', type=bool, default=True, help='verbosity of the script') + parser.add_argument('-v', '--verbose', dest='verbose', action='store_true') + parser.add_argument('--no-verbose', dest='verbose', action='store_false') + parser.set_defaults(verbose=True) args = vars(parser.parse_args()) sys.exit(compare_vtk(args["vtk_file_1"], args["vtk_file_2"], args["absolute"], args["relative"], args["zeroThreshold"], args["verbose"])) diff --git a/bin/testing/runtest.py b/bin/testing/runtest.py index 4967075550584b206d6e372821bbd1d864901ee2..4f1b301b78eb0dd011cadb2f44a01e5fbfebbee0 100755 --- a/bin/testing/runtest.py +++ b/bin/testing/runtest.py @@ -1,5 +1,6 @@ #!/usr/bin/env python import argparse +import shlex import os, sys import subprocess import json @@ -34,7 +35,7 @@ if args['script']: # run the test res = 1 try: - res = subprocess.call(args['command'][0].split()) + res = subprocess.call(shlex.split(args['command'][0])) except OSError as e: print(args['command'][0].split()) print("OSError: Command not found. Most likely the executable specified doesn't exist.") diff --git a/cmake.opts b/cmake.opts new file mode 100644 index 0000000000000000000000000000000000000000..a05cc4e545286a3d705b7796ced0f2cc4ccffcb9 --- /dev/null +++ b/cmake.opts @@ -0,0 +1,56 @@ +GXX_RELEASE_WARNING_OPTS=" \ + -Wall \ + -Wunused \ + -Wmissing-include-dirs \ + -Wcast-align \ + -Wno-missing-braces \ + -Wmissing-field-initializers \ + -Wno-sign-compare" + +GXX_RELEASE_OPTS=" \ + -fdiagnostics-color=always \ + -fno-strict-aliasing \ + -fstrict-overflow \ + -fno-finite-math-only \ + -DNDEBUG=1 \ + -O3 \ + -march=native \ + -funroll-loops \ + -g0" + +SPECIFIC_COMPILER="" +# if you want to specify a specific compiler, do it by setting (comment the above line) +#SPECIFIC_COMPILER=" +# -DCMAKE_C_COMPILER=/usr/bin/gcc-8 +# -DCMAKE_CXX_COMPILER=/usr/bin/g++-8 +#" + +SPECIFIC_GENERATOR="" +# if you want to specify a specific make file generator (e.g. ninja), do it by setting (comment the above line) +#SPECIFIC_GENERATOR=" +# -DCMAKE_GENERATOR='Ninja' +# -DCMAKE_MAKE_PROGRAM='/usr/bin/ninja' +#" + +OPM_FLAGS="" +# to build opm it might be necessary to set manually the following variables (comment the above line) +#OPM_FLAGS=" +#-Decl_DIR=[/path/to]/libecl/build +#-DUSE_MPI=ON +#" + +# set this to "ON" if you want to be able to have the headercheck target +DUMUX_ENABLE_HEADERCHECK=OFF + +# for debug opts you can set DCMAKE_BUILD_TYPE to "Debug" or "RelWithDebInfo" +# you can also do this in any of the CMakeLists.txt in Dumux +# just rerun cmake again afterwards (run cmake ) + +CMAKE_FLAGS="$SPECIFIC_COMPILER $SPECIFIC_GENERATOR $OPM_FLAGS +-DCMAKE_CXX_FLAGS_RELEASE='$GXX_RELEASE_OPTS $GXX_RELEASE_WARNING_OPTS' +-DCMAKE_CXX_FLAGS_DEBUG='-O0 -g -ggdb -Wall -Wextra -Wno-unused-parameter -Wno-sign-compare' +-DCMAKE_CXX_FLAGS_RELWITHDEBINFO='$GXX_RELEASE_OPTS $GXX_RELEASE_WARNING_OPTS -g -ggdb -Wall' +-DCMAKE_BUILD_TYPE=Release +-DENABLE_HEADERCHECK=$DUMUX_ENABLE_HEADERCHECK +-DDUNE_GRID_EXPERIMENTAL_GRID_EXTENSIONS:BOOL=TRUE +" diff --git a/cmake/modules/DumuxMacros.cmake b/cmake/modules/DumuxMacros.cmake index d89484b592551353e431229e845e437df7bef7b5..3b878c92947bf3b6c0eb36d7e93ade77acb0745a 100644 --- a/cmake/modules/DumuxMacros.cmake +++ b/cmake/modules/DumuxMacros.cmake @@ -8,7 +8,9 @@ find_package(GLPK) find_package(Gnuplot) set(HAVE_GNUPLOT ${GNUPLOT_FOUND}) find_package(Gstat) +find_package(Gmsh) find_package(NLOPT) find_package(PTScotch) find_package(PVPython) find_package(Valgrind) +find_package(Quadmath) diff --git a/cmake/modules/DumuxTestMacros.cmake b/cmake/modules/DumuxTestMacros.cmake index af926f43750c3263d209c75b42a7517b2fbff6b1..fd437823f1983d6256cbe0260c8042c405e58609 100644 --- a/cmake/modules/DumuxTestMacros.cmake +++ b/cmake/modules/DumuxTestMacros.cmake @@ -14,7 +14,7 @@ ### macro(add_dumux_test dumux_test dumux_test_executable dumux_test_executable_source) - message(WARNING "add_dumux_test is deprecated. Use dune_add_test directly now that we require dune 2.5") + message(WARNING "add_dumux_test is deprecated. Use dune_add_test directly now that we require dune 2.6") # if present, symlink the grids folder set(grids_directory ${CMAKE_CURRENT_SOURCE_DIR}/grids) diff --git a/cmake/modules/FindGmsh.cmake b/cmake/modules/FindGmsh.cmake new file mode 100644 index 0000000000000000000000000000000000000000..5fa395e0a4d89b43c0c6439a893c3d3bf89fb1b4 --- /dev/null +++ b/cmake/modules/FindGmsh.cmake @@ -0,0 +1,50 @@ +# .. cmake_module:: +# +# Find the Gmsh meshing tool +# +# You may set the following variables to modify the +# behaviour of this module: +# +# :ref:`GMSH_ROOT` +# Path list to search for gmsh. +# +# Sets the following variables: +# +# :code:`gmsh_FOUND` +# True if the gmsh library was found. +# +# :code:`GMSH_EXECUTABLE` +# Path to gmsh executable +# +# .. cmake_variable:: GMSH_ROOT +# +# You may set this variable to have :ref:`FindGmsh` look +# for the gmsh library in the given path before inspecting +# system paths. +# + +# look for header files, only at positions given by the user +find_program(GMSH_EXECUTABLE + NAMES gmsh + PATHS "${GMSH_ROOT}" + "${CMAKE_SOURCE_DIR}/../" + "/usr/bin/" + PATH_SUFFIXES "src" "external/gmsh/src" "gmsh/src" "gmsh" + NO_DEFAULT_PATH +) + +include(FindPackageHandleStandardArgs) +find_package_handle_standard_args( + "gmsh" + DEFAULT_MSG + GMSH_EXECUTABLE +) + +# set macros for config.h +set(HAVE_GMSH ${gmsh_FOUND}) +set(GMSH_EXECUTABLE ${GMSH_EXECUTABLE}) + +# text for feature summary +set_package_properties("Gmsh" PROPERTIES + DESCRIPTION "Meshing tool" + PURPOSE "Generate structured and unstructured grids") diff --git a/cmake/modules/FindGstat.cmake b/cmake/modules/FindGstat.cmake index a19d48171782a0a37b497a2828f750ea61ce9a7c..8931f20a67af2308e5bb1fe07c78304d863cb9c5 100644 --- a/cmake/modules/FindGstat.cmake +++ b/cmake/modules/FindGstat.cmake @@ -28,7 +28,7 @@ find_program(GSTAT_EXECUTABLE NAMES gstat PATHS "${GSTAT_ROOT}" "${CMAKE_SOURCE_DIR}/../" - "usr/bin/" + "/usr/bin/" PATH_SUFFIXES "src" "external/gstat/src" "gstat/src" "gstat" NO_DEFAULT_PATH ) diff --git a/cmake/modules/FindQuadmath.cmake b/cmake/modules/FindQuadmath.cmake new file mode 100644 index 0000000000000000000000000000000000000000..874d8efe67677f69994e862de2665ec6fd6ae339 --- /dev/null +++ b/cmake/modules/FindQuadmath.cmake @@ -0,0 +1,48 @@ +# Module that checks whether the compiler supports the +# quadruple precision floating point math +# +# Sets the following variables: +# HAVE_QUAD +# QUADMATH_LIBRARIES +# +# perform tests +include(CheckCSourceCompiles) +include(CheckCXXSourceCompiles) +include(CMakePushCheckState) +include(CheckCXXCompilerFlag) + +if(NOT DEFINED USE_QUADMATH OR USE_QUADMATH) + if(NOT DEFINED HAVE_EXTENDED_NUMERIC_LITERALS) + check_cxx_compiler_flag("-Werror -fext-numeric-literals" HAVE_EXTENDED_NUMERIC_LITERALS) + endif() + + if (HAVE_EXTENDED_NUMERIC_LITERALS) + set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fext-numeric-literals") + endif() + + cmake_push_check_state(RESET) + list(APPEND CMAKE_REQUIRED_LIBRARIES "quadmath") + CHECK_CXX_SOURCE_COMPILES(" +#include +int main(void){ + __float128 foo = sqrtq(123.456); + foo = FLT128_MIN; +}" QUADMATH_FOUND) + cmake_pop_check_state() + + if (QUADMATH_FOUND) + set(QUADMATH_LIBRARIES "quadmath") + set(HAVE_QUAD "${QUADMATH_FOUND}") + endif() +endif() + +if (USE_QUADMATH AND NOT QUADMATH_FOUND) + message(FATAL_ERROR "Quadruple precision math support was explicitly requested but is unavailable!") +endif() + +include(FindPackageHandleStandardArgs) +find_package_handle_standard_args(Quadmath + DEFAULT_MSG + QUADMATH_LIBRARIES + HAVE_QUAD + ) diff --git a/config.h.cmake b/config.h.cmake index aee39426a82ac0849bad7fdbe7fd05d505298a94..04807297455da0e0511801214c0ad5f419ab939b 100644 --- a/config.h.cmake +++ b/config.h.cmake @@ -40,6 +40,9 @@ /* Define to the revision of dumux */ #define DUMUX_VERSION_REVISION ${DUMUX_VERSION_REVISION} +/* Define the path to dumux */ +#define DUMUX_SOURCE_DIR "${CMAKE_SOURCE_DIR}" + /* Define to 1 if Valgrind was found */ #cmakedefine HAVE_VALGRIND 1 @@ -55,6 +58,21 @@ /* Define path to gstat executable */ #cmakedefine GSTAT_EXECUTABLE "@GSTAT_EXECUTABLE@" +/* Define to 1 if gmsh was found */ +#cmakedefine HAVE_GMSH 1 + +/* Define path to gmsh executable */ +#cmakedefine GMSH_EXECUTABLE "@GMSH_EXECUTABLE@" + +/* Defines whether pvpython has been found */ +#cmakedefine HAVE_PVPYTHON 1 + +/* Define the path to pvpython */ +#define PVPYTHON_EXECUTABLE "${PVPYTHON_EXECUTABLE}" + +/* Define to 1 if quadmath was found */ +#cmakedefine HAVE_QUAD 1 + /* end dumux Everything below here will be overwritten */ diff --git a/debug.opts b/debug.opts deleted file mode 100644 index b8d070510829924d716bbd70f223bf9bc20fc07c..0000000000000000000000000000000000000000 --- a/debug.opts +++ /dev/null @@ -1,28 +0,0 @@ -GXX_WARNING_OPTS=" \ - -Wall \ - -Wunused \ - -Wmissing-include-dirs \ - -Wcast-align \ - -Wno-sign-compare \ - -Wno-unused-parameter" - -# additional -W flags for g++ which will lead to many warnings -# -Wextra \ -# -Wfloat-equal \ -# -Wstrict-overflow \ - -GXX_OPTS=" \ - -fno-strict-aliasing \ - -fstrict-overflow \ - -g" - -# configure flags -CMAKE_FLAGS="\ - -DCMAKE_CXX_FLAGS=\"$GXX_WARNING_OPTS $GXX_OPTS\" \ - -DUG_DIR=ug_installation_path \ - " - -# optional configure flags -# for the CO2 and CO2ni tests enable the experimental grid extension -# and make sure the module dune-alugrid is present -# -DDUNE_GRID_EXPERIMENTAL_GRID_EXTENSIONS=TRUE \ diff --git a/doc/doxygen/DoxygenDumuxLayout.xml b/doc/doxygen/DoxygenDumuxLayout.xml index 3cfe34c877d9e8546d0bb6917fc5d309eb2dbb60..e9d42835a406e55851c77235a7c7022907aacfd5 100644 --- a/doc/doxygen/DoxygenDumuxLayout.xml +++ b/doc/doxygen/DoxygenDumuxLayout.xml @@ -131,7 +131,7 @@ - + diff --git a/doc/doxygen/Doxylocal b/doc/doxygen/Doxylocal index 26c28840846a166b246a788e66d50b71c06b84c2..4c084904896d00bca0b7087c92bd344856eca970 100644 --- a/doc/doxygen/Doxylocal +++ b/doc/doxygen/Doxylocal @@ -14,9 +14,8 @@ INPUT += @srcdir@/mainpage.txt \ @srcdir@/modules.txt \ @top_srcdir@/dumux \ @top_srcdir@/test \ - @top_srcdir@/tutorial \ - @srcdir@/extradoc/parameterlist.txt \ - @srcdir@/extradoc/featurelist.txt + # @srcdir@/extradoc/parameterlist.txt \ # we currently do not have a parameter list. Should be back for 3.1 + # @srcdir@/extradoc/featurelist.txt # we currently do not have a feature list. Should be back for 3.1 EXAMPLE_PATH += @srcdir@/extradoc @@ -26,11 +25,9 @@ EXTRA_PACKAGES += amsmath,amssymb,units LAYOUT_FILE = @srcdir@/DoxygenDumuxLayout.xml -HTML_EXTRA_STYLESHEET = @srcdir@/customdoxygendumux.css - -HTML_COLORSTYLE_HUE = 37 +HTML_HEADER = @srcdir@/header.html -HTML_COLORSTYLE_SAT = 206 +HTML_EXTRA_STYLESHEET = @srcdir@/customdoxygendumux.css EXCLUDE_PATTERNS = diff --git a/doc/doxygen/customdoxygendumux.css b/doc/doxygen/customdoxygendumux.css index df09ae1acf454c85e2d3b535801af27e11559061..351de7d0b463cd28f3495faca8d2cb9e721753c5 100644 --- a/doc/doxygen/customdoxygendumux.css +++ b/doc/doxygen/customdoxygendumux.css @@ -2,6 +2,7 @@ body, table, div, p, dl { font: 400 14px/22px Roboto,sans-serif; + min-width: 500px } p.reference, p.definition { @@ -133,9 +134,9 @@ a.qindex { a.qindexHL { font-weight: bold; - background-color: #ffcd78; + background-color: #9CAFD4; color: #ffffff; - border: 1px double #f5bf5b; + border: 1px double #869DCA; } .contents a.qindexHL:visited { @@ -396,8 +397,8 @@ span.vhdllogic { } blockquote { - background-color: #fefaf5; - border-left: 2px solid #f7cb78; + background-color: #F7F8FB; + border-left: 2px solid #9CAFD4; margin: 0 24px 0 4px; padding: 0 12px 0 16px; } @@ -476,7 +477,7 @@ table.memberdecls { .mdescLeft, .mdescRight, .memItemLeft, .memItemRight, .memTemplItemLeft, .memTemplItemRight, .memTemplParams { - background-color: #fefbf5; + background-color: #F9FAFC; border: none; margin: 4px; padding: 1px 0 0 8px; @@ -524,7 +525,7 @@ table.memberdecls { margin-bottom: -1px; background-image: url('nav_f.png'); background-repeat: repeat-x; - background-color: #fdf0d8; + background-color: #E2E8F2; line-height: 1.25; font-weight: 300; float:left; @@ -591,7 +592,7 @@ table.memberdecls { color: #253555; font-weight: bold; text-shadow: 0px 1px 1px rgba(255, 255, 255, 0.9); - background-color: #fceed4; + background-color: #DFE5F1; /* opera specific markup */ box-shadow: 5px 5px 5px rgba(0, 0, 0, 0.15); border-top-right-radius: 4px; @@ -610,9 +611,9 @@ table.memberdecls { } .memdoc, dl.reflist dd { - border-bottom: 1px solid #f8d087; - border-left: 1px solid #f8d087; - border-right: 1px solid #f8d087; + border-bottom: 1px solid #A8B8D9; + border-left: 1px solid #A8B8D9; + border-right: 1px solid #A8B8D9; padding: 6px 10px 2px 10px; background-color: #FBFCFD; border-top-width: 0; @@ -724,8 +725,8 @@ span.mlabel { div.directory { margin: 10px 0px; - border-top: 1px solid #98ABD2; - border-bottom: 1px solid #98ABD2; + border-top: 1px solid #9CAFD4; + border-bottom: 1px solid #9CAFD4; width: 100%; } @@ -763,7 +764,7 @@ div.directory { .directory tr.even { padding-left: 6px; - background-color: #fef8ec; + background-color: #F7F8FB; } .directory img { @@ -785,7 +786,7 @@ div.directory { } .arrow { - color: #98ABD2; + color: #9CAFD4; -webkit-user-select: none; -khtml-user-select: none; -moz-user-select: none; @@ -889,7 +890,7 @@ table.doxtable td, table.doxtable th { } table.doxtable th { - background-color: #cc8500; + background-color: #374F7F; color: #FFFFFF; font-size: 110%; padding-bottom: 4px; @@ -899,7 +900,7 @@ table.doxtable th { table.fieldtable { /*width: 100%;*/ margin-bottom: 10px; - border: 1px solid #f8d087; + border: 1px solid #A8B8D9; border-spacing: 0px; -moz-border-radius: 4px; -webkit-border-radius: 4px; @@ -915,8 +916,8 @@ table.fieldtable { .fieldtable td.fieldtype, .fieldtable td.fieldname { white-space: nowrap; - border-right: 1px solid #f8d087; - border-bottom: 1px solid #f8d087; + border-right: 1px solid #A8B8D9; + border-bottom: 1px solid #A8B8D9; vertical-align: top; } @@ -925,7 +926,7 @@ table.fieldtable { } .fieldtable td.fielddoc { - border-bottom: 1px solid #f8d087; + border-bottom: 1px solid #A8B8D9; /*width: 100%;*/ } @@ -944,7 +945,7 @@ table.fieldtable { .fieldtable th { background-image:url('nav_f.png'); background-repeat:repeat-x; - background-color: #fdf0d8; + background-color: #E2E8F2; font-size: 90%; color: #253555; padding-bottom: 4px; @@ -957,7 +958,7 @@ table.fieldtable { -webkit-border-top-right-radius: 4px; border-top-left-radius: 4px; border-top-right-radius: 4px; - border-bottom: 1px solid #f8d087; + border-bottom: 1px solid #A8B8D9; } @@ -1071,7 +1072,7 @@ div.header { background-image:url('nav_h.png'); background-repeat:repeat-x; - background-color: #fefbf5; + background-color: #F9FAFC; margin: 0px; border-bottom: 1px solid #C4CFE5; } @@ -1164,7 +1165,6 @@ dl.section dd { #projectlogo img { border: 0px none; - padding-bottom: 10px; } #projectalign @@ -1174,24 +1174,21 @@ dl.section dd { #projectname { - color: #ffffff; - font: 100% Tahoma, Arial,sans-serif; + font: 300% Tahoma, Arial,sans-serif; margin: 0px; - padding: 7px 0px; + padding: 0px 0px; } #projectbrief { font: 120% Tahoma, Arial,sans-serif; margin: 0px; - padding-left: 55px; - padding-bottom: 10px; + padding-bottom: 0px; } #projectnumber { - color: #000000; - font: 150% Tahoma, Arial,sans-serif; + font: 50% Tahoma, Arial,sans-serif; margin: 0px; padding: 0px; } @@ -1236,7 +1233,7 @@ dl.section dd { div.zoom { - border: 1px solid #f6c56a; + border: 1px solid #90A5CE; } dl.citelist { diff --git a/doc/doxygen/extradoc/featurelist.txt b/doc/doxygen/extradoc/featurelist.txt index 091b69f3641a0879a454807cf87e1685f9644fd3..5030f9041bc9292073da18e36f7c2f3a563b7b32 100644 --- a/doc/doxygen/extradoc/featurelist.txt +++ b/doc/doxygen/extradoc/featurelist.txt @@ -27,7 +27,7 @@ * | :- | :- | * | \c container/test_container_io | Test for writing and reading sequence container to and from file | * | \c gnuplotinterface/test_gnuplotinterface | tests the plotting of data sets, functions, and files | - * | \c gridcreator/test_gridcreator_gmsh | Test for gmsh interface of the grid creator | + * | \c gridmanager/test_gridmanager_gmsh | Test for gmsh interface of the grid manager | * * \section Implicit * | Tests | | Fluidsystem | Gridmanager | Mass/Mole | Non-/Isothermal | Discretization | linearSolver | AdaptiveGrid | BoundaryCondition | Homogeneity | MaterialLaw | Permeability | Gravity | JacobianRecycling | PartialReassemble | Comments | diff --git a/doc/doxygen/header.html b/doc/doxygen/header.html new file mode 100644 index 0000000000000000000000000000000000000000..361cba1c81817a5e3e7ad37bd3027647a52d9227 --- /dev/null +++ b/doc/doxygen/header.html @@ -0,0 +1,56 @@ + + + + + + + + +$projectname: $title +$title + + + +$treeview +$search +$mathjax + +$extrastylesheet + + +
+ + +
+ + + + + + + + + + + + + + + + + + + + + +
+
+ $projectnumber +
+
$projectbrief
+ 		+
$projectbrief
+ 		$searchbox
+
+ + diff --git a/doc/doxygen/images/staggered_halfelementwise.png b/doc/doxygen/images/staggered_halfelementwise.png new file mode 100644 index 0000000000000000000000000000000000000000..2cff88a6136a856734a1f276ff90a4e2f3620f8f Binary files /dev/null and b/doc/doxygen/images/staggered_halfelementwise.png differ diff --git a/doc/doxygen/images/staggered_halfelementwise.svg b/doc/doxygen/images/staggered_halfelementwise.svg new file mode 100644 index 0000000000000000000000000000000000000000..66d1c84416b52263f499a9fa733cb9bb58df1cee --- /dev/null +++ b/doc/doxygen/images/staggered_halfelementwise.svg @@ -0,0 +1,1117 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + FVCells + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + staggered control volume + + + + + + + scvf + + diff --git a/doc/doxygen/images/staggeredgeometry.png b/doc/doxygen/images/staggeredgeometry.png new file mode 100644 index 0000000000000000000000000000000000000000..0a484898a34a797c522e23a0452ae3778216f4eb Binary files /dev/null and b/doc/doxygen/images/staggeredgeometry.png differ diff --git a/doc/doxygen/images/staggeredgeometry.svg b/doc/doxygen/images/staggeredgeometry.svg new file mode 100644 index 0000000000000000000000000000000000000000..c153cd8e7b2524a9f972817b68bc2fcc4c0e8741 --- /dev/null +++ b/doc/doxygen/images/staggeredgeometry.svg @@ -0,0 +1,1163 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + element + subcontrolvolume + + scvf/selfFacet + + dofIndexSelf + + + dofIndexOpposite + + + + + + pairData[0].outerParallel + + + + + pairData[1].outerParallel + + + pairData[0].normalPair.second + + + + pairData[0].normalPair.first + + + + + + pairData[1].normalPair.second + + + + + pairData[1].normalPair.first + + + + neighboring element + + current element + clockwise/ counter clockwisewith respect to the intersection(with a clock being in the element) + 2 + 0 + 3 + localNormalFaceIdx + here: horizontal velocities + here: vertical velocities + + pairData[0].globalCommonEntIdx + pairData[1].globalCommonEntIdx + parallelFacet + + selfToOppositeDistance + + + + + normalDistance + parallelDistance + + + + + + 1 + + diff --git a/doc/doxygen/modules.txt b/doc/doxygen/modules.txt index 61d4b02aec0c0904822eabf97486e00591dec3cb..b0c15db748d059fc72c9e1d9f0774bf323c8ba4f 100644 --- a/doc/doxygen/modules.txt +++ b/doc/doxygen/modules.txt @@ -16,17 +16,17 @@ * \brief Single-phase (immiscible) Darcy flow * \copydetails ./porousmediumflow/1p/model.hh */ - /*! - * \ingroup OnePModel - * \defgroup SequentialOnePModel Sequential - * \brief Sequential single-phase (immiscible) Darcy flow - * - * # Pressure - * \copydetails ./porousmediumflow/1p/sequential/diffusion/cellcentered/pressure.hh - * - * # Velocity - * \copydetails ./porousmediumflow/1p/sequential/diffusion/cellcentered/velocity.hh - */ + /*! + * \ingroup OnePModel + * \defgroup SequentialOnePModel Sequential + * \brief Sequential single-phase (immiscible) Darcy flow + * + * # Pressure + * \copydetails Dumux::FVPressure1P + * + * # Velocity + * \copydetails Dumux::FVVelocity1P + */ /*! * \ingroup PorousmediumflowModels * \defgroup OnePNCModel 1pnc @@ -51,10 +51,10 @@ * \brief Sequential two-phase (immiscible) Darcy flow * * # Pressure - * \copydetails ./porousmediumflow/2p/sequential/diffusion/cellcentered/pressure.hh + * \copydetails Dumux::FVPressure2P * * # Velocity - * \copydetails ./porousmediumflow/2p/sequential/diffusion/cellcentered/velocity.hh + * \copydetails Dumux::FVVelocity2P */ /*! * \ingroup PorousmediumflowModels @@ -74,10 +74,10 @@ * \brief Sequential two-phase, two-component Darcy flow * * # Pressure - * \copydetails ./porousmediumflow/2p2c/sequential/fvpressure.hh + * \copydetails Dumux::FVPressure2P2C * * # Velocity - * \copydetails ./porousmediumflow/2p2c/sequential/fvtransport.hh + * \copydetails Dumux::FVTransport2P2C */ /*! * \ingroup PorousmediumflowModels @@ -109,6 +109,12 @@ * \brief Three-phase, two-component Darcy flow with water (liquid & gas) and oil * \copydetails ./porousmediumflow/3pwateroil/model.hh */ + /*! + * \ingroup PorousmediumflowModels + * \defgroup BoxDFMModel boxdfm + * \brief \todo + * \copydetails ./porousmediumflow/boxdfm/model.hh + */ /*! * \ingroup PorousmediumflowModels * \defgroup CO2Model CO2 @@ -131,13 +137,13 @@ */ /*! * \ingroup PorousmediumflowModels - * \defgroup PorousmediumNonEquilibriumModel NonEquilibrium + * \defgroup NonEquilibriumModel NonEquilibrium * \brief Model that adds nonequilibrium equations to another porous medium flow model (only used in MPNCModel currently) * \copydetails ./porousmediumflow/nonequilibrium/model.hh */ - /*! - * \ingroup PorousmediumNonEquilibriumModel - * \defgroup PorousmediumThermalNonEquilibriumModel ThermalNonEquilibrium + /*! + * \ingroup NonEquilibriumModel + * \defgroup ThermalNonEquilibriumModel ThermalNonEquilibrium * \brief Model that adapts the energy localresidual to thermal nonequilibrium * \copydetails ./porousmediumflow/nonequilibrium/thermal/localresidual.hh */ @@ -160,6 +166,12 @@ * \brief Richards multi-component flow * \copydetails ./porousmediumflow/richardsnc/model.hh */ + /*! + * \ingroup PorousmediumflowModels + * \defgroup SolidEnergyModel Solid energy + * \brief Energy equation for the solid (general heat equation) + * \copydetails ./porousmediumflow/solidenergy/model.hh + */ /*! * \ingroup PorousmediumflowModels * \defgroup TracerModel Tracer @@ -170,137 +182,245 @@ /* ***************** FreeflowModels ******************/ /*! * \defgroup FreeflowModels Free Flow Models - * \brief Single-phase Navier Stokes / Stokes model + * \brief Single-phase models basing on the Navier-Stokes equation */ - /*! + /*! * \ingroup FreeflowModels - * \defgroup NavierStokesModel NavierStokes - * \brief Single-phase Navier Stokes flow + * \defgroup NavierStokesModel Navier-Stokes + * \brief Single-phase Navier-Stokes flow * \copydetails ./freeflow/navierstokes/model.hh */ /*! * \ingroup FreeflowModels - * \defgroup NavierStokesNCModel NavierStokes nc - * \brief Single-phase multi-component Navier Stokes flow - * \copydetails ./freeflow/navierstokesnc/model.hh + * \defgroup RANSModel Reynolds-Averaged Navier-Stokes + * \brief Single-phase Reynolds-Averaged Navier-Stokes flow + * \copydetails ./freeflow/rans/model.hh + */ + /*! + * \ingroup RANSModel + * \defgroup ZeroEqModel 0-Eq. Models + * \brief Zero-equation or algebraic turbulence models + * \copydetails ./freeflow/rans/zeroeq/model.hh + */ + /*! + * \ingroup RANSModel + * \defgroup OneEqModel 1-Eq. Models + * \brief One-equation turbulence model by Spalart-Allmaras + * \copydetails ./freeflow/rans/oneeq/model.hh + */ + /*! + * \ingroup RANSModel + * \defgroup TwoEqModel 2-Eq. Models + * \brief Two-equation turbulence models + */ + /*! + * \ingroup TwoEqModel + * \defgroup KEpsilonModel K-epsilon model + * \brief K-epsilon model + * \copydetails ./freeflow/rans/twoeq/kepsilon/model.hh + */ + /*! + * \ingroup TwoEqModel + * \defgroup KOmegaModel K-omega model + * \brief K-omega model + * \copydetails ./freeflow/rans/twoeq/komega/model.hh + */ + /*! + * \ingroup TwoEqModel + * \defgroup LowReKEpsilonModel Low-Re k-epsilon model + * \brief Low-Re k-epsilon model + * \copydetails ./freeflow/rans/twoeq/lowrekepsilon/model.hh + */ + /*! + * \ingroup FreeflowModels + * \defgroup FreeflowNCModel Compositional + * \brief Single-phase multi-component free-flow flow models + * \copydetails ./freeflow/compositional/navierstokesncmodel.hh */ /*! * \ingroup FreeflowModels - * \defgroup NavierStokesNIModel nonisothermal - * \brief An energy equation adaptor for isothermal Navier Stokes models + * \defgroup FreeflowNIModel Nonisothermal + * \brief An energy equation adaptor for isothermal free-flow models * \copydetails ./freeflow/nonisothermal/model.hh */ + /*! + * \ingroup FreeflowModels + * \defgroup ShallowWaterModel 2D shallow water model + * \brief Two-dimensional shallow water flow (depth-averaged) + * \copydetails ./freeflow/shallowwater/model.hh + */ +/*! + * \defgroup Geomechanics Geomechanics Models + * \brief Models for taking into account solid deformation + */ + /*! + * \ingroup Geomechanics + * \defgroup Elastic Solid mechanics w/o fluid pressure + * \brief Models linear elastic deformation of a solid. Disregards fluid pressure. + * \copydetails ./geomechanics/elastic/model.hh + */ + /*! + * \ingroup Geomechanics + * \defgroup PoroElastic Solid mechanics with fluid pressure + * \brief Models linear elastic deformation of a solid. Takes fluid pressure into account. + * \copydetails ./geomechanics/poroelastic/model.hh + */ /* ***************** Benchmarks and Tests ******************/ /*! * \defgroup BenchmarksAndTests Benchmarks and Tests * \brief Benchmarks and tests used for (automated) testing and demonstration purposes */ - /*! - * \ingroup BenchmarksAndTests - * \defgroup PorousmediumflowTests Porous-Medium Flow Tests - * \brief Single and multi-phase tests for flow and transport in porous materials - */ - /*! - * \ingroup PorousmediumflowTests - * \defgroup OnePTests 1p (one phase) benchmarks and tests - * \brief Various tests using a OnePModel. The files are listed below. - */ - /*! - * \ingroup PorousmediumflowTests - * \defgroup OnePNCTests 1pnc (one phase, multi-component) benchmarks and tests - * \brief Various tests using a OnePNCModel. The files are listed below. - */ - /*! - * \ingroup PorousmediumflowTests - * \defgroup OnePNCMinTests 1pncmin (one phase, multi-component mineralization) benchmarks and tests - * \brief Various tests using the OnePNCMinModel. The files are listed below. - */ - /*! - * \ingroup PorousmediumflowTests - * \defgroup TwoPTests 2p (two phase) benchmarks and tests - * \brief Various tests using a TwoPModel. The files are listed below. - */ - /*! - * \ingroup PorousmediumflowTests - * \defgroup TwoPOneCTests 2p1c (two phase, one component) benchmarks and tests - * \brief Various tests using the TwoPOneCModel. The files are listed below. - */ - /*! - * \ingroup PorousmediumflowTests - * \defgroup TwoPTwoCTests 2p2c (two phase, two component) benchmarks and tests - * \brief Various tests using a TwoPTwoCModel. The files are listed below. - */ - /*! - * \ingroup PorousmediumflowTests - * \defgroup TwoPNCTests 2pnc (two phase, multi-component) benchmarks and tests - * \brief A fuel cell test problem using the TwoPNCModel. The files are listed below. - */ - /*! - * \ingroup PorousmediumflowTests - * \defgroup TwoPNCMinTests 2pncmin (two phase, multi-component mineralization) benchmarks and tests - * \brief A salt dissolution test problem using the TwoPNCMinModel. The files are listed below. - */ - /*! - * \ingroup PorousmediumflowTests - * \defgroup ThreePTests 3p (three phase) benchmarks and tests - * \brief Various tests using a ThreePModel. The files are listed below. - */ - /*! - * \ingroup PorousmediumflowTests - * \defgroup ThreePThreeCTests 3p3c (three phase, three component) benchmarks and tests - * \brief Various tests using a ThreePThreeCModel. The files are listed below. - */ - /*! - * \ingroup PorousmediumflowTests - * \defgroup ThreePWaterOilTests 3pwateroil (three phase, water oil) benchmarks and tests - * \brief A SAGD test problem using the ThreePWaterOilModel. The files are listed below. - */ - /*! - * \ingroup PorousmediumflowTests - * \defgroup CO2Tests CO2 (two phase, two component) benchmarks and tests - * \brief A CO2 injection test problem using the TwoPTwoCModel and heterogeneous spatial parameters. The files are listed below. - */ - /*! - * \ingroup PorousmediumflowTests - * \defgroup MPNCTests MPNC (multi-phase, multi-component) benchmarks and tests - * \brief Various tests using the MPNCModel. The files are listed below. - */ - /*! - * \ingroup PorousmediumflowTests - * \defgroup RichardsTests Richards benchmarks and tests - * \brief Various tests using a RichardsModel. The files are listed below. - */ - /*! - * \ingroup PorousmediumflowTests - * \defgroup RichardsNCTests Richards multi-component benchmarks and tests - * \brief A multi-component transport problem in the unsaturated zone using the RichardsNCModel. The files are listed below. - */ - /*! - * \ingroup PorousmediumflowTests - * \defgroup TracerTests Tracer benchmarks and tests - * \brief Various tests using a TracerModel. The files are listed below. - */ - /*! - * \ingroup BenchmarksAndTests - * \defgroup FreeflowTests Free Flow Tests - * \brief Varios tests for single-phase Navier Stokes / Stokes tests - */ - /*! - * \ingroup FreeflowTests - * \defgroup NavierStokesTests Single-phase Navier Stokes tests - * \brief Various tests using a Single-phase Navier Stokes flow. The files are listed below. - */ - /*! - * \ingroup FreeflowTests - * \defgroup NavierStokesNCTests Single-phase Navier Stokes nc tests - * \brief Various tests using a Single-phase Navier Stokes flow. The files are listed below. - */ - /*! - * \ingroup BenchmarksAndTests - * \defgroup MaterialTests Material system tests - * \brief Benchmarks and Test(s) for the material system. - */ + /*! + * \ingroup BenchmarksAndTests + * \defgroup PorousmediumflowTests Porous-Medium Flow Tests + * \brief Single and multi-phase tests for flow and transport in porous materials + */ + /*! + * \ingroup PorousmediumflowTests + * \defgroup OnePTests 1p (one phase) benchmarks and tests + * \brief Various tests using a OnePModel. The files are listed below. + */ + /*! + * \ingroup PorousmediumflowTests + * \defgroup OnePNCTests 1pnc (one phase, multi-component) benchmarks and tests + * \brief Various tests using a OnePNCModel. The files are listed below. + */ + /*! + * \ingroup PorousmediumflowTests + * \defgroup OnePNCMinTests 1pncmin (one phase, multi-component mineralization) benchmarks and tests + * \brief Various tests using the OnePNCMinModel. The files are listed below. + */ + /*! + * \ingroup PorousmediumflowTests + * \defgroup TwoPTests 2p (two phase) benchmarks and tests + * \brief Various tests using a TwoPModel. The files are listed below. + */ + /*! + * \ingroup PorousmediumflowTests + * \defgroup TwoPOneCTests 2p1c (two phase, one component) benchmarks and tests + * \brief Various tests using the TwoPOneCModel. The files are listed below. + */ + /*! + * \ingroup PorousmediumflowTests + * \defgroup TwoPTwoCTests 2p2c (two phase, two component) benchmarks and tests + * \brief Various tests using a TwoPTwoCModel. The files are listed below. + */ + /*! + * \ingroup PorousmediumflowTests + * \defgroup TwoPNCTests 2pnc (two phase, multi-component) benchmarks and tests + * \brief A fuel cell test problem using the TwoPNCModel. The files are listed below. + */ + /*! + * \ingroup PorousmediumflowTests + * \defgroup TwoPNCMinTests 2pncmin (two phase, multi-component mineralization) benchmarks and tests + * \brief A salt dissolution test problem using the TwoPNCMinModel. The files are listed below. + */ + /*! + * \ingroup PorousmediumflowTests + * \defgroup ThreePTests 3p (three phase) benchmarks and tests + * \brief Various tests using a ThreePModel. The files are listed below. + */ + /*! + * \ingroup PorousmediumflowTests + * \defgroup ThreePThreeCTests 3p3c (three phase, three component) benchmarks and tests + * \brief Various tests using a ThreePThreeCModel. The files are listed below. + */ + /*! + * \ingroup PorousmediumflowTests + * \defgroup ThreePWaterOilTests 3pwateroil (three phase, water oil) benchmarks and tests + * \brief A SAGD test problem using the ThreePWaterOilModel. The files are listed below. + */ + /*! + * \ingroup PorousmediumflowTests + * \defgroup CO2Tests CO2 (two phase, two component) benchmarks and tests + * \brief A CO2 injection test problem using the TwoPTwoCModel and heterogeneous spatial parameters. The files are listed below. + */ + /*! + * \ingroup PorousmediumflowTests + * \defgroup MPNCTests MPNC (multi-phase, multi-component) benchmarks and tests + * \brief Various tests using the MPNCModel. The files are listed below. + */ + /*! + * \ingroup PorousmediumflowTests + * \defgroup RichardsTests Richards benchmarks and tests + * \brief Various tests using a RichardsModel. The files are listed below. + */ + /*! + * \ingroup PorousmediumflowTests + * \defgroup RichardsNCTests Richards multi-component benchmarks and tests + * \brief A multi-component transport problem in the unsaturated zone using the RichardsNCModel. The files are listed below. + */ + /*! + * \ingroup PorousmediumflowTests + * \defgroup TracerTests Tracer benchmarks and tests + * \brief Various tests using a TracerModel. The files are listed below. + */ + /*! + * \ingroup BenchmarksAndTests + * \defgroup FreeflowTests Free Flow Tests + * \brief Various tests for single-phase Navier-Stokes / Stokes tests + */ + /*! + * \ingroup FreeflowTests + * \defgroup NavierStokesTests Single-phase Navier-Stokes tests + * \brief Various tests using a single-phase Navier-Stokes flow. The files are listed below. + */ + /*! + * \ingroup FreeflowTests + * \defgroup NavierStokesNCTests Single-phase Navier-Stokes nc tests + * \brief Various tests using a single-phase Navier-Stokes flow with n components. The files are listed below. + */ + /*! + * \ingroup FreeflowTests + * \defgroup RANSTests Reynolds-Averaged Navier-Stokes tests + * \brief Various tests using a single-phase Reynolds-Averaged Navier-Stokes flow. The files are listed below. + */ + /*! + * \ingroup FreeflowTests + * \defgroup RANSNCTests Reynolds-Averaged Navier-Stokes nc tests + * \brief Various tests using a single-phase Reynolds-Averaged Navier-Stokes flow with n components. The files are listed below. + */ + /*! + * \ingroup FreeflowTests + * \defgroup ShallowWaterTests 2D shallow water tests + * \brief Tests for the two-dimensional shallow water model. The files are listed below. + */ + /*! + * \ingroup BenchmarksAndTests + * \defgroup GeomechanicsTests Geomechanics Tests + * \brief Various tests using the geomechanics elastic or poroelastic models. The files are listed below. + */ + /*! + * \ingroup BenchmarksAndTests + * \defgroup MaterialTests Material system tests + * \brief Benchmarks and Test(s) for the material system. + */ + /*! + * \ingroup BenchmarksAndTests + * \defgroup MultiDomainTests MultiDomain tests + * \brief Various tests for multidomain problems. + */ + /*! + * \ingroup MultiDomainTests + * \defgroup BoundaryTests MultiDomain boundary tests + * \brief Various tests using a boundary as coupling interface: Darcy-Stokes coupling or PNM (pore network model)-Darcy. The files are listed below. + */ + /*! + * \ingroup MultiDomainTests + * \defgroup EmbeddedTests Embedded MultiDomain tests + * \brief Various tests for embedded coupling problems with different dimensions: Root-soil interaction or embedded fracture models. The files are listed below. + */ + /*! + * \ingroup MultiDomainTests + * \defgroup FacetTests Facet MultiDomain tests + * \brief Various tests for facet coupling problems with different dimensions: Discrete facet conforming fracture models and problems with physics on a domain surface. The files are listed below. + */ + /*! + * \ingroup MultiDomainTests + * \defgroup PoromechanicsTests Facet MultiDomain tests + * \brief Various tests coupling poromechanics and fluid flow. The files are listed below. + */ /* ***************** Discretization ******************/ /*! @@ -316,7 +436,7 @@ * \ingroup Discretization * \defgroup CCDiscretization Cell-centered FV scheme * \brief Finite volume schemes with degrees of freedom located at grid cell centers. - */ + */ /*! * \ingroup CCDiscretization * \defgroup CCTpfaDiscretization Two-point flux approximation (Tpfa) @@ -332,7 +452,46 @@ * \defgroup StaggeredDiscretization Staggered FV scheme * \brief A staggered finite volume scheme with degrees of freedom at cell-centers and facets. */ - + /*! + * \ingroup Discretization + * \defgroup FEMDiscretization Finite element method + * \brief The finite element method + */ +/* ***************** Flux ******************/ +/*! + * \defgroup Flux Flux + * \brief All flux related things available in DuMux + */ + /*! + * \ingroup Flux + * \defgroup BoxFlux Flux related to the Box scheme + * \brief Flux related to the box scheme + */ + /*! + * \ingroup Flux + * \defgroup CCFlux Flux related to the cell-centered schemes + * \brief Flux related to the cell-centered schemes + */ + /*! + * \ingroup Flux + * \defgroup CCTpfaFlux Flux related to the cell-centered two-point flux approximation schemes + * \brief Flux related to the cell-centered two-point flux approximation schemes + */ + /*! + * \ingroup Flux + * \defgroup CCMpfaFlux Flux related to the cell-centered multi-point flux approximation schemes + * \brief Flux related to the cell-centered multi-point flux approximation schemes + */ + /*! + * \ingroup Flux + * \defgroup StaggeredFlux Flux related to the staggered scheme + * \brief Flux related to the staggered scheme + */ + /*! + * \ingroup Flux + * \defgroup ShallowWaterFlux Flux related to the shallow water model + * \brief Flux related to the shallow water model + */ /* ***************** Material ******************/ /*! * \defgroup Material Material and Fluid Framework @@ -343,14 +502,15 @@ * - __Binary coefficient:__
@copydoc Binarycoefficients * - __Chemistry:__
@copydoc Chemistry * - __Component:__
@copydoc Components - * - __Constraint solver:__
@copydoc ConstraintSolver + * - __Constraint solvers:__
@copydoc ConstraintSolvers * - __Equation of state:__
@copydoc EOS * - __Fluid-Matrix Interactions:__
@copydoc Fluidmatrixinteractions * - __Fluid state:__
@copydoc FluidStates + * - __Solid state:__
@copydoc SolidStates * - __Fluid system:__
@copydoc Fluidsystems * - __Spatial Parameters:__
@copydoc SpatialParameters */ - /*! + /*! * \ingroup Material * \defgroup Binarycoefficients Binary Coefficients * \brief Binary coefficients @@ -374,23 +534,21 @@ /*! * \ingroup Material * \defgroup Components Components - * \brief Components: building blocks for fluid systems + * \brief thermodynamics of single chemical species or fixed mixtures of species * - * Components are fluid systems which provide the - * thermodynamic relations for the liquid and gas phase of a single - * chemical species or a fixed mixture of species. Their main purpose - * is to provide a convenient way to access these quantities from - * full-fledged fluid systems. Components are not supposed to be used - * by models directly. - */ - /*! + * Components provide the thermodynamic relations for the liquid, + * gaseous and/or solid state of a single + * chemical species or a _fixed_ mixture of species. + * Fluid systems use components to compute thermodynamic quantities of phases. + */ + /*! * \ingroup Components * \defgroup IAPWS IAPWS * \brief Tabulated values according to the International Association for the Properties of Water and Steam (IAPWS) */ /*! * \ingroup Material - * \defgroup ConstraintSolver Constraint Solver + * \defgroup ConstraintSolvers Constraint Solvers * \brief Constraint solvers converting primary to secondary variables * * Constraint solvers are auxiliary tools to @@ -450,6 +608,30 @@ * decision since the thermodynamic state of the system is expressed by * a fluid state! */ + /*! + * \ingroup Material + * \defgroup SolidStates Solid States + * \brief Solid states are responsible for representing all relevant + * thermodynamic quantities of solid systems. + * + * A solid state provides access methods + * to __all__ thermodynamic quantities, but the concept of a solid state does not + * mandate what assumptions are made to store these thermodynamic + * quantities. What solid states also do __not__ do is to make sure + * that the thermodynamic state which they represent is physically + * possible. + */ + /*! + * \ingroup Material + * \defgroup SolidSystems Solid Systems + * \brief Solid systems express the thermodynamic relations (functions). + * + * Since functions do + * not exhibit any internal state, solid systems are stateless classes, + * i.e. all member functions are static. This is a conscious + * decision since the thermodynamic state of the system is expressed by + * a solid state! + */ /*! * \ingroup Material * \defgroup SpatialParameters Spatial Parameters @@ -467,43 +649,90 @@ * \brief Adaptive grids */ -/* ***************** Assembly ******************/ +/* ***************** Assembly and Solvers ******************/ /*! - * \defgroup Assembly Assembly - * \brief Assembly of linear systems (Jacobian and residual) + * \defgroup AssemblyAndSolvers Assembly and Solvers + * \brief Assembling matrices and vectors, solvers for linear and nonlinear equations */ -/* ***************** Common ******************/ -/*! - * \defgroup Common Common - * \brief Common classes, functions, properties and concepts - */ - /*! - * \ingroup Common - * \defgroup Properties Properties - * \brief Basic properties of all models in DuMux - */ - -/* ***************** InputOutput ******************/ +/* ***************** Assembly ******************/ /*! - * \defgroup InputOutput Input Output - * \brief Classes and functions dealing with input and output of data and grids + * \ingroup AssemblyAndSolvers + * \defgroup Assembly Assembly + * \brief Assembly of linear systems (Jacobian and residual) */ /* ***************** Linear ******************/ /*! + * \ingroup AssemblyAndSolvers * \defgroup Linear Linear * \brief Linear solvers and helpers */ /* ***************** Nonlinear ******************/ /*! + * \ingroup AssemblyAndSolvers * \defgroup Nonlinear Nonlinear * \brief Nonlinear solvers: Newton method */ -/* ***************** Parallel ******************/ + /* ***************** Common ******************/ /*! - * \defgroup Parallel Parallel - * \brief Helpers for parallel runs with MPI + * \defgroup Common Common + * \brief Common classes, functions, properties and concepts */ + /*! + * \ingroup Common + * \defgroup Geometry Geometry + * \brief Basic geometries in DuMux + */ + /*! + * \ingroup Common + * \defgroup Properties Properties + * \brief Basic properties of all models in DuMux + */ + /*! + * \ingroup Common + * \defgroup Typetraits Typetraits + * \brief Basic Type traits in DuMux + */ + +/* ***************** InputOutput ******************/ +/*! + * \defgroup InputOutput Input Output + * \brief Classes and functions dealing with input and output of data and grids + */ + +/* ***************** MultiDomain ******************/ +/*! + * \defgroup MultiDomain Multidomain simulations + * \brief Classes to run problems with multiple domains + * + * The multi domain module allows to couple regular DuMux problems. + * Several coupling modes are currently available. + */ + /*! + * \ingroup MultiDomain + * \defgroup BoundaryCoupling Boundary coupling mode + * \brief Couples problems of different or equal dimension that touch at the domain boundary. Examples are equal-dimension multi-physics problems like Darcy-Stokes coupling or PNM (pore network model)-Darcy coupling. + */ + /*! + * \ingroup BoundaryCoupling + * \defgroup DarcyDarcyCoupling Darcy-Darcy domain coupling + * \brief Couples domains with equal-dimension multi-physics problems in a Darcy-Darcy coupling. + */ + /*! + * \ingroup BoundaryCoupling + * \defgroup StokesDarcyCoupling Stokes-Darcy domain coupling + * \brief Couples domains with equal-dimension multi-physics problems in a Stokes-Darcy coupling. + */ + /*! + * \ingroup MultiDomain + * \defgroup EmbeddedCoupling Embedded mixed-dimension coupling mode + * \brief Couples problems of different dimensions where one or more lower-dimensional problems (lowdim) are embedded in a higher-dimensional domain (bulk). Examples are embedded one-dimensional networks for the simulation of blood tissue perfusion, or root-soil interaction, and embedded fracture models. + */ + /*! + * \ingroup MultiDomain + * \defgroup FacetCoupling Conforming mixed-dimension facet coupling mode + * \brief Couples problems of different dimensions where one or more lower-dimensional problems (lowdim) live on the facets of the higher-dimensional domain (bulk). Examples are discrete facet conforming fracture models and problems with physics on a domain surface. + */ diff --git a/doc/doxygen/sanitizelinks.sh b/doc/doxygen/sanitizelinks.sh index 52051da2fa7d8214253c7c6af94f39cb1bf70232..76a4079b17e28991a5845e49c5cb76f57ee32790 100755 --- a/doc/doxygen/sanitizelinks.sh +++ b/doc/doxygen/sanitizelinks.sh @@ -1,2 +1,7 @@ #make the modules page default view clearer (toggleLevel(1)) -sed -i 's/\(init_search();\)/\1 toggleLevel(1);/' html/modules.html +if [ -e html/modules.html ]; then + sed -i 's/\(init_search();\)/\1 toggleLevel(1);/' html/modules.html +fi +if [ -e html/modules.HTML ]; then + sed -i 's/\(init_search();\)/\1 toggleLevel(1);/' html/modules.HTML +fi diff --git a/doc/handbook/0_dumux-handbook.tex b/doc/handbook/0_dumux-handbook.tex index 0a2416b866fa6490e81cffb4fc34f1439d5ba11e..59d04dabe737d01037987ffa7b62fbc19e9fb41f 100644 --- a/doc/handbook/0_dumux-handbook.tex +++ b/doc/handbook/0_dumux-handbook.tex @@ -11,8 +11,8 @@ \usepackage{enumerate} \usepackage{hyperref} \usepackage{graphicx} + \usepackage{listings} -\usepackage{makeidx} \usepackage[square,numbers]{natbib} \usepackage{pdflscape} \usepackage{rotating} @@ -72,6 +72,7 @@ \DeclareMathOperator{\grad}{\mathbf{grad}} \DeclareMathOperator{\curl}{curl} \DeclareMathOperator{\Div}{div} +\newcommand{\meas}[1]{\lvert{#1}\rvert} \pagestyle{scrheadings} @@ -96,8 +97,6 @@ Universit\"at Stuttgart, Paffenwaldring 61, D-70569 Stuttgart, Germany}\\ {\normalsize \texttt{\url{http://dumux.org}}}\\ } -\makeindex - \begin{document} \maketitle @@ -109,45 +108,50 @@ Universit\"at Stuttgart, Paffenwaldring 61, D-70569 Stuttgart, Germany}\\ \chapter{Introduction} \input{1_introduction} -\chapter{Getting started} +\chapter{Quick Start}\label{quick-install} In this chapter we provide a quick start guide to -your first \Dumux experience. -The first section contains instructions on how to very quickly install \Dumux. -More detailed information on how to obtain source code, build and test \Dune and \Dumux -follows in the second section of this chapter. The second section also contains information on -how to build the documentation and about external libraries and modules. +your first \Dumux experience, including an install script with all necessary instructions +on how to very quickly install the latest release version of \Dumux. +You should have a recent working Linux environment. +If you need more information, please have a look at the detailed installation +instructions in the next chapter \ref{detailed-install}. \input{2_quickinstall} -\input{2_detailedinstall} -\chapter{Tutorial}\label{chp:tutorial} -\input{3_tutorial} -\input{3_furtherpractice} +\chapter{Detailed Installation, Documentation, and Externals}\label{detailed-install} +In this chapter, we provide more detailed information on how to obtain source code, build and test \Dune and \Dumux. +It further contains information on +how to build the documentation and about external libraries and modules. +\input{3_detailedinstall} + +\chapter{Learning to use \Dumux}\label{chp:tutorial} +\input{4_course} +\input{4_furtherpractice} \chapter{Overview and Infrastructure} This chapter provides an overview of the general structure in \Dumux \ref{sc_structure} and gives help for basic work with \Dumux -(\ref{sc_newfoldersetup},\ref{sc_parameterfiles},\ref{sc_restartsimulations},\ref{sc_guidelines},\ref{sc_developingdumux}). +(\ref{sc_newfoldersetup},\ref{sc_parameterfiles},\ref{sc_restartsimulations}, \ref{sc_developingdumux}). Further it presents useful external tools \ref{sc_externaltools} and basic concepts \ref{sc_linearsystem}. -\input{4_structure} -\input{4_newfoldersetup} -\input{4_parameterfiles} -\input{4_restartsimulations} -\input{4_guidelines} -\input{4_developingdumux} -\input{4_externaltools} -\input{4_assemblinglinearsystem} +\input{5_structure} +\input{5_newfoldersetup} +\input{5_parameterfiles} +\input{5_restartsimulations} +\input{5_developingdumux} +\input{5_externaltools} +\input{5_assemblinglinearsystem} \chapter{Advanced \Dumux\ -- Detailed Instructions} This chapter contains detailed information for those who are interested in deeper modifications of underlying \Dumux models, classes, functions, etc. -\input{5_models} -\input{5_spatialdiscretizations} -\input{5_stepsofasimulation} -\input{5_propertysystem} -\input{5_grids} +\input{6_basics} +\input{6_temporaldiscretizations} +\input{6_spatialdiscretizations} +\input{6_stepsofasimulation} +\input{6_propertysystem} +\input{6_inputoutput} +\input{6_parallel} \bibliographystyle{plainnat} \bibliography{dumux-handbook} -\printindex \end{document} diff --git a/doc/handbook/1_introduction.tex b/doc/handbook/1_introduction.tex index 526f021c8ae803a42309073bac542d5bdbc8626e..705d692420fe6924edbae2a7e97923501011367b 100644 --- a/doc/handbook/1_introduction.tex +++ b/doc/handbook/1_introduction.tex @@ -7,7 +7,7 @@ processor systems to highly parallel supercomputers with specialized hardware architectures. The means to achieve these somewhat contradictory goals are the -thorough use of object oriented design in conjunction with template +thorough use of object-oriented design in conjunction with template programming. These requirements call for \Cplusplus as the implementation language. @@ -25,7 +25,7 @@ libraries\footnote{In fact, the performance penalty resulting from the use of \Dune's grid interface is usually negligible~\cite{BURRI2006}.}. \begin{figure}[hbt] \centering - \includegraphics[width=.5\linewidth, keepaspectratio]{PNG/dunedesign.png} + \includegraphics[width=.5\linewidth, keepaspectratio]{png/dunedesign.png} \caption{ \label{fig:dune-design} A high-level overview of \Dune's design is available on the project's @@ -37,7 +37,7 @@ DUNE's grid interface is independent of the spatial dimension of the underlying grid. For this purpose, it uses the concept of co-dimensional entities. Roughly speaking, an entity of co-dimension $0$ constitutes a cell, co-dimension $1$ entities are faces between -cells, co-dimension $1$ are edges, and so on until co-dimension $n$ +cells, co-dimension $2$ are edges, and so on until co-dimension $n$ which are the cell's vertices. The \Dune grid interface generally assumes that all entities are convex polytopes, which means that it must be possible to express each entity as the convex hull of a set of @@ -49,7 +49,10 @@ entity can be thought of as a prototype for the actual grid entity. For example, if we used a grid which applied hexahedrons as cells, the reference element for each cell would be the unit cube $[0, 1]^3$ and the geometry function would scale and translate the cube so that -it matches the grid's cell. For a more thorough description of \Dune's +it matches the grid's cell. A quick overview of reference elements and the +related numbering can be obtained from the DUNE cheat sheet +(\url{https://www.dune-project.org/pdf/dune-cheat-sheet.pdf}). +For a more thorough description of \Dune's grid definition, see~\cite{BASTIAN2008}. In addition to the grid interface, \Dune also provides quite a few @@ -63,7 +66,7 @@ solving the generated systems. \Dumux comes in form of an additional module \texttt{dumux}. It depends on the \Dune core modules -\texttt{dune-common}, \texttt{dune-grid}, \texttt{dune-istl}, and on \texttt{dune-localfunctions}. +\texttt{dune-common}, \texttt{dune-grid}, \texttt{dune-istl}, and \texttt{dune-localfunctions}. The main intention of \Dumux is to provide a framework for an easy and efficient implementation of new physical models for porous media flow problems, ranging from problem formulation and the selection of @@ -71,3 +74,17 @@ spatial and temporal discretization schemes as well as nonlinear solvers, to general concepts for model coupling. Moreover, \Dumux includes ready to use numerical models and a few example applications. +This is the handbook to a new major version update of \Dumux: version 3.0. +The release contains considerable improvements and many new features compared to the 2.x versions. +Due to the major update, backwards compatibility with the last release 2.12 cannot be assured. +To facilitate the transition for our users, we have created a +git wiki entry describing how to update programs from version 2.12 to version 3.0. +It is available online: +\url{https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/wikis/Updating-programs-from-version-2.12-to-version-3.0}. +The guide leads in detail through the interface changes from 2.12 to 3.0, +concerning the \texttt{Problem} class, the \texttt{SpatialParams} class, +the \texttt{Parameters} and \texttt{Properties}, i.e. the main user interface. +Starting with version 3.0.0, all minor +version updates will certainly be backward compatible again with at least the last minor version. +We highly recommend all our users to transition with us to \Dumux-3.0 +and wish everyone a brand-new and exciting simulation experience. diff --git a/doc/handbook/2_quickinstall.tex b/doc/handbook/2_quickinstall.tex index 91a4139a886b9fe9c24338d7d5fc9ad3df1f82c5..668f22ca4e4c04d96817dc24d0661b9d165d2b46 100644 --- a/doc/handbook/2_quickinstall.tex +++ b/doc/handbook/2_quickinstall.tex @@ -1,34 +1,17 @@ -\section{Quick Installation of \Dumux} -\label{quick-install} - -This section only provides one quick way of installing \Dumux. -You should have a recent working Linux environment and no \Dune core modules should be installed. -If you need more information or -have \Dune already installed, please have a look at the detailed installation -instructions in Section \ref{install}. - -\subsection{Prerequisites} \label{sec:prerequisites} +\section{Prerequisites} \label{sec:prerequisites} For this quick start guide the following software packages are required: \begin{itemize} \item GitLab client \item A standard compliant C++ compiler supporting C++11 and the C++14 feature set of GCC 4.9. We support GCC 4.9 or newer and Clang 3.8 or newer. \item CMake 2.8.12 or newer \item pkg-config -\item paraview (to visualize the results) +\item ParaView (to visualize the results) \end{itemize} -The building of included documentation like this handbook requires \LaTeX{} and auxiliary tools -\texttt{bibtex}. One usually chooses a \LaTeX{} distribution like \texttt{texlive} for this purpose. -It is possible to switch off the building of the documentation by setting the switch \texttt{--disable-documentation} -in the \texttt{CONFIGURE\_FLAGS} of the building options, see Chapter \ref{buildIt}. - -\subsection{Obtaining code and configuring all modules with a script} +\section{Obtaining code and configuring all modules with a script} We provide you with a shell-script \texttt{installDumux.sh} that facilitates setting up a {\Dune}/{\Dumux} directory tree and configures all modules with CMake. -% TODO: uncomment/delete the following lines when next is the only release -% It is available after obtaining a download link via \url{http://www.dumux.org/download/} or -% by copying the following lines into a text-file named \texttt{installDumux.sh}: -Copy the following lines into a text-file named \texttt{installDumux.sh}: +Copy the following lines into a text file named \texttt{installDumux.sh}: \lstinputlisting[style=DumuxCode, numbersep=5pt, firstline=1, firstnumber=1]{installDumux.sh} Place the \texttt{installDumux.sh} script in the directory where you want to install \Dumux and \Dune (a single @@ -36,19 +19,21 @@ root folder \texttt{DUMUX} will be produced, so you do not need to provide one). Run the script by typing into the terminal: \texttt{./installDumux.sh} Configuring \Dune and \Dumux is done by the command-line script \texttt{dunecontrol} -using optimized configure options, see the line entitled \texttt{\# run build} in the \texttt{installDumux.sh} script. +using optimized configure options, see the line entitled \texttt{\# run build} in the \texttt{installDumux.sh} script. More details about the build-system can be found in section \ref{buildIt}. \subsection{A first test run of \Dumux} When the \texttt{installDumux.sh} script from the subsection above has run successfully, you can execute a second script that -will compile and run a simple one-phase ground water flow example and will visualize the result using paraview. -The test script can be obtained by copying the following lines into a text-file named \texttt{test\_dumux.sh} +will compile and run a simple one-phase ground water flow example and will visualize the result using ParaView. +The test script can be obtained by copying the following lines into a text file named \texttt{test\_dumux.sh} that has to be located in the same directory as the installation script. \begin{lstlisting}[style=DumuxCode] -cd DUMUX/dumux/build-cmake/test/porousmediumflow/1p/implicit -make -B test_1pcctpfa -./test_1pcctpfa test_1pcctpfa.input +cd DUMUX/dumux/build-cmake/test/porousmediumflow/1p/implicit/isothermal +make -B test_1p_tpfa +./test_1p_tpfa params.input paraview *pvd \end{lstlisting} The script \texttt{test\_dumux.sh} can be executed by typing into the terminal: \texttt{./test\_dumux.sh}. -If everything works fine, a paraview-window with the result should open automatically. +If everything works fine, a ParaView window with the result should open automatically, showing the initial +conditions. Advance ParaView to the next frame (green arrow button) and rescale to data range to admire +the colorful pressure distribution. diff --git a/doc/handbook/2_detailedinstall.tex b/doc/handbook/3_detailedinstall.tex similarity index 55% rename from doc/handbook/2_detailedinstall.tex rename to doc/handbook/3_detailedinstall.tex index 504d33049e51056871dfa4dbed86a9e060cf7ac6..8abe54e971e3e8d74e3459a8e1a87bb20f4dbef8 100644 --- a/doc/handbook/2_detailedinstall.tex +++ b/doc/handbook/3_detailedinstall.tex @@ -1,13 +1,10 @@ -\section{Detailed Installation Instructions} -\label{install} - Installing \Dumux means that you first unpack \Dune and \Dumux in a root directory, (section \ref{sc:ObtainingSourceCode}). In a second step of the installation, all modules are configured with CMake (section \ref{buildIt}). -After successfull installation of \Dumux we guide you to start a test application, +After successful installation of \Dumux, we guide you to start a test application, described in section \ref{quick-start-guide}. -In section \ref{sec:build-doxy-doc} we explain how to build the \Dumux documentation. +In section \ref{sec:build-doc} we explain how to build the \Dumux documentation. Lastly, section \ref{sec:external-modules-libraries} provides details on optional libraries and modules. In a technical sense \Dumux is a module of \Dune. @@ -15,67 +12,64 @@ Thus, the installation procedure of \Dumux is the same as that of \Dune. Details regarding the installation of \Dune are provided on the \Dune website \cite{DUNE-HP}. -\subsection{Obtaining Source Code for \Dune and \Dumux} +\section{Obtaining Source Code for \Dune and \Dumux} \label{sc:ObtainingSourceCode} The \Dumux release and trunk (developer tree) are based on the most recent -\Dune release 2.5, comprising the core modules dune-common, dune-geometry, dune-grid, -dune-istl and dune-localfunctions. For working with \Dumux, these modules are required. +\Dune release 2.6, comprising the core modules \texttt{dune-common}, \texttt{dune-geometry}, +\texttt{dune-grid}, \texttt{dune-istl} and \texttt{dune-localfunctions}. +For working with \Dumux, these modules are required. All \Dune modules, including the \Dumux module, get extracted into a common root directory, as it is done in an ordinary \Dune installation. We usually name our root directory \texttt{DUMUX} but an arbitrary name can be chosen. -Source code files for each \Dune module are contained in their own subdirectory within the root directory. -The subdirectories for the modules are named after the module names (depending on how -the modules were obtained a version number is added to the module name). +Source code files for each \Dune module are contained in their own sub-directory within the root directory. +The sub-directories for the modules are named after the module names (depending on how +the modules were obtained, a version number is added to the module name). The name of each \Dune module is defined in the file \texttt{dune.module}, which is in the root directory of the respective module. This should not be changed by the user. Two possibilities exist to get the source code of \Dune and \Dumux. Firstly, \Dune and \Dumux can be downloaded as tar files from the respective \Dune and \Dumux website. They have to be extracted as described in the next paragraph. -% TODO: alpha version was not released with a tarball. For the next releases the following lines need to be deleted again -There is no tar file for the current \DumuxVersion~release. -Secondly, a method to obtain the most recent source code (or, more generally, any of its previous revisions) by direct access -to the software repositories of the revision control system is described in the subsequent part. -Be aware that you cannot get \texttt{dumux-devel} or the external libraries from \texttt{dumux-external} unless -you have an GitLab account with the right privileges. +Secondly, the most recent source code +(or, more generally, any of its previous revisions) can be obtained by direct access +to the software repositories of the revision control system. This is described in the second paragraph. In section \ref{sec:prerequisites} we list some prerequisites for running \Dune and \Dumux. Please check in said paragraph whether you can fulfill them before continuing. -% TODO: alpha version was not released with a tarball. For the next releases the following lines need to be uncommented again -% \paragraph{Obtaining the software by installing tar files} -% The slightly old-fashionedly named tape-archive-file, shortly named tar file or -% tarball, is a common file format for distributing collections of files contained -% within these archives. -% The extraction from the tar files is done as follows: -% Download the tarballs from the respective \Dune (version 2.5) and \Dumux websites -% to a certain folder in your file system. -% Create the common root directory, named \texttt{DUMUX} in the example below. -% Then extract the content of the tar files, e.\,g. with the command-line program -% \texttt{tar}. -% This can be achieved by the following shell commands. Replace \texttt{path\_to\_tarball} -% with the directory name where the downloaded files are actually located. -% After extraction, the actual name of the dumux subdirectory is \texttt{dumux-\DumuxVersion} -% (or whatever version you downloaded). -% -% \begin{lstlisting}[style=Bash] -% $ mkdir DUMUX -% $ cd DUMUX -% $ tar xzvf path_to_tarball_of/dune-common-2.5.0.tar.gz -% $ tar xzvf path_to_tarball_of/dune-geometry-2.5.0.tar.gz -% $ tar xzvf path_to_tarball_of/dune-grid-2.5.0.tar.gz -% $ tar xzvf path_to_tarball_of/dune-istl-2.5.0.tar.gz -% $ tar xzvf path_to_tarball_of/dune-localfunctions-2.5.0.tar.gz -% $ tar xzvf path_to_tarball_of/dumux-3.0-alpha.tar.gz -% \end{lstlisting} -% -% Furthermore, if you wish to install the optional \Dune Grid-Howto which provides a tutorial -% on the Dune grid interface, act similar. +\paragraph{Obtaining the software by installing tar files} +The slightly old-fashionedly named tape-archive-file, shortly named tar file or +tarball, is a common file format for distributing collections of files contained +within these archives. +The extraction from the tar files is done as follows: +Download the tarballs from the respective \Dune (version 2.6) and \Dumux websites +to a certain folder in your file system. +Create the common root directory, named \texttt{DUMUX} in the example below. +Then extract the content of the tar files, e.\,g. with the command-line program +\texttt{tar}. +This can be achieved by the following shell commands. Replace \texttt{path\_to\_tarball} +with the directory name where the downloaded files are actually located. +After extraction, the actual name of the dumux subdirectory is \texttt{dumux-\DumuxVersion} +(or whatever version you downloaded). + +\begin{lstlisting}[style=Bash] +$ mkdir DUMUX +$ cd DUMUX +$ tar xzvf path_to_tarball_of/dune-common-2.6.0.tar.gz +$ tar xzvf path_to_tarball_of/dune-geometry-2.6.0.tar.gz +$ tar xzvf path_to_tarball_of/dune-grid-2.6.0.tar.gz +$ tar xzvf path_to_tarball_of/dune-istl-2.6.0.tar.gz +$ tar xzvf path_to_tarball_of/dune-localfunctions-2.6.0.tar.gz +$ tar xzvf path_to_tarball_of/dumux-3.0.tar.gz +\end{lstlisting} + +Furthermore, if you wish to install the optional \Dune Grid-Howto which provides a tutorial +on the Dune grid interface, act similar. \paragraph{Obtaining \Dune and \Dumux from software repositories} Direct access to a software revision control system for downloading code can be of advantage later on. It is easier to keep up with code changes and to receive important bug fixes. -\Dune and \Dumux use Git for their software repositories. To access them a Git client is needed. +\Dune and \Dumux use Git for their software repositories. To access them, a Git client is needed. In the technical language of Git, \emph{cloning a certain software version} means nothing more then fetching a local copy from the software repository and laying it out in the file system. @@ -93,65 +87,59 @@ one for \Dune and one for \Dumux. \begin{lstlisting}[style=Bash] $ mkdir DUMUX $ cd DUMUX -$ git clone -b releases/2.5 https://gitlab.dune-project.org/core/dune-common.git -$ git clone -b releases/2.5 https://gitlab.dune-project.org/core/dune-geometry.git -$ git clone -b releases/2.5 https://gitlab.dune-project.org/core/dune-grid.git -$ git clone -b releases/2.5 https://gitlab.dune-project.org/core/dune-istl.git -$ git clone -b releases/2.5 https://gitlab.dune-project.org/core/dune-localfunctions.git -$ git clone -b 3.0.0-alpha https://git.iws.uni-stuttgart.de/dumux-repositories/dumux.git +$ git clone -b releases/2.6 https://gitlab.dune-project.org/core/dune-common.git +$ git clone -b releases/2.6 https://gitlab.dune-project.org/core/dune-geometry.git +$ git clone -b releases/2.6 https://gitlab.dune-project.org/core/dune-grid.git +$ git clone -b releases/2.6 https://gitlab.dune-project.org/core/dune-istl.git +$ git clone -b releases/2.6 https://gitlab.dune-project.org/core/dune-localfunctions.git +$ git clone -b releases/3.0 https://git.iws.uni-stuttgart.de/dumux-repositories/dumux.git \end{lstlisting} The newest and maybe unstable developments of \Dune and \Dumux are also provided in these repositories and can be found in the \emph{master} branch. Please check the \Dune website \cite{DUNE-HP} for further information on the \Dune development. We always try to keep up with the latest developments of \Dune. -However, the current \Dumux release is based on the stable 2.5 release and it might not compile without further adaptations using the newest versions of \Dune. +However, the current \Dumux release is based on the stable 2.6 release and it might not compile without further adaptations using the newest versions of \Dune. Furthermore, if you wish to install the optional \Dune Grid-Howto which provides a tutorial on the Dune grid interface, act similar. -\paragraph{Patching \Dune or external libraries} -\label{sc:patchingDUNE} -Patching of \Dune modules in order to work together with \Dumux can be necessary for several reasons. -Software like a compiler or even a standard library -changes at times. But, for example, a certain release of a software component that we depend on, -may not reflect that change and thus it has to be modified. -In the dynamic developing process of software which depends on other modules it is not always feasible -to adapt everything to the most recent version of each module. They may fix problems with a certain module -of a certain release without introducing too much structural change. - -\Dumux contains patches and documentation about their usage and application within the -directory \texttt{dumux/patches}. -Please check the README file in that directory for recent information. -In general, a patch can be applied as follows -(the exact command or the used parameters may be slightly different). -We include here an example of a patching dune-grid. - -\begin{lstlisting}[style=Bash] -$ # make sure you are in the common root directory -$ cd dune-grid -$ patch -p0 < ../dumux/patches/grid-2.3.1.patch -\end{lstlisting} - -It can be removed by -\begin{lstlisting}[style=Bash] -$ path -p0 -R < ../dumux/patches/grid-2.3.1.patch -\end{lstlisting} - -\paragraph{Hints for \Dumux-Developers} -If you also want to actively participate in the development of \Dumux, you can allways send patches -to the Mailing list. -To get more involved, you can apply either for full developer -access or for developer access on certain parts of \Dumux. Granted developer access means that -you are allowed to commit own code and that you can access the \texttt{dumux-devel} module. -This enhances \texttt{dumux} by providing maybe unstable code from the developer group. +%TODO:currently, no DUNE patches necessary! Uncomment this section in case this changes again in the future. +% +% \paragraph{Patching \Dune or external libraries} +% \label{sc:patchingDUNE} +% Patching of \Dune modules in order to work together with \Dumux can be necessary for several reasons. +% Software like a compiler or even a standard library +% changes at times. But, for example, a certain release of a software component that we depend on, +% may not reflect that change and thus it has to be modified. +% In the dynamic developing process of software which depends on other modules it is not always feasible +% to adapt everything to the most recent version of each module. They may fix problems with a certain module +% of a certain release without introducing too much structural change. +% +% \Dumux contains patches and documentation about their usage and application within the +% directory \texttt{dumux/patches}. +% Please check the README file in that directory for recent information. +% In general, a patch can be applied as follows +% (the exact command or the used parameters may be slightly different). +% We include here an example of a patching dune-grid. +% +% \begin{lstlisting}[style=Bash] +% $ # make sure you are in the common root directory +% $ cd dune-grid +% $ patch -p0 < ../dumux/patches/grid-2.3.1.patch +% \end{lstlisting} +% +% It can be removed by +% \begin{lstlisting}[style=Bash] +% $ path -p0 -R < ../dumux/patches/grid-2.3.1.patch +% \end{lstlisting} -\subsection{Build of \Dune and \Dumux} +\section{Build of \Dune and \Dumux} \label{buildIt} Configuring \Dune and \Dumux is done by the shell-command \texttt{dunecontrol} which is part of the \Dune build system. If you are interested in more details about the build system that is used, -they can be found in the \Dune buildsystem documentation\footnote{\url{https://www.dune-project.org/buildsystem/}} and +they can be found in the \Dune build system documentation\footnote{\url{https://www.dune-project.org/buildsystem/}} and CMake's documentation\footnote{\url{https://cmake.org/documentation/}}. -If something fails during the execution of \texttt{dunecontrol} feel free to report it to the \Dune or \Dumux developer mailing list, -but also try to include error details. +If something fails during the execution of \texttt{dunecontrol}, feel free to report it to the \Dune or \Dumux developer mailing list, +but please include error details. It is possible to compile \Dumux with nearly no explicit options to the build system. However, for the successful compilation of \Dune and \Dumux, it is currently necessary to pass @@ -163,85 +151,80 @@ $ ./dune-common/bin/dunecontrol --configure-opts="CXXFLAGS=-fno-strict-aliasing" \end{lstlisting} Too many options can make life hard. That's why usually option files are being used together with \texttt{dunecontrol} and its sub-tools. -Larger sets of options are kept in them. If you are going to compile with options suited for debugging the code, the following +Larger sets of options are kept in them. If you are going to compile with modified options, the following can be a starting point: \begin{lstlisting}[style=Bash] $ # make sure you are in the common root directory -$ cp dumux/debug.opts my-debug.opts # create a personal version -$ gedit my-debug.opts # optional editing the options file -$ ./dune-common/bin/dunecontrol --opts=my-debug.opts --use-cmake all -\end{lstlisting} - -More optimized code, which is typically not usable for standard debugging tasks, can be produced by -\begin{lstlisting}[style=Bash] -$ cp dumux/optim.opts my-optim.opts -$ ./dune-common/bin/dunecontrol --opts=my-optim.opts --use-cmake all +$ cp dumux/cmake.opts my-cmake.opts # create a personal version +$ gedit my-cmake.opts # optional editing the options file +$ ./dune-common/bin/dunecontrol --opts=my-cmake.opts all \end{lstlisting} -Sometimes it is necessary to have additional options which +Sometimes, it is necessary to have additional options which are specific to a package set of an operating system or sometimes you have your own preferences. Feel free to work with your own set of options, which may evolve over time. -The option files above are to be understood more as a starting point +The option file that comes with the distribution is to be understood more as a starting point for setting up an own customization than as something which is fixed. The use of external libraries can make it necessary to add quite many options in an option file. It can be helpful to give your customized option file its own name, as done above, to avoid confusing it with the option files which came out of the distribution. -\subsection{The First Run of a Test Application} +\section{The First Run of a Test Application} \label{quick-start-guide} -The previous section showed how to install and compile \Dumux. This chapter +The previous section showed how to install and compile \Dumux. This section shall give a very brief introduction how to run a first test application and how -to visualize the first output files. A more detailed explanations can be found in -the tutorials in the following chapter.\\ -All executables are compiled in the \texttt{build} subdirectories of \Dumux. -If not given differently in the input files, this is \texttt{build-cmake} as default. +to visualize the first output files.\par +All executables are compiled in the \texttt{build} sub-directories of \Dumux. +If not specified differently in the options file, this is \texttt{build-cmake} as default. \begin{enumerate} -\item Go to the directory \texttt{build-cmake/test}. There, various test application - folders can be found. Let us consider as example\\ - \texttt{porousmediumflow/2p/implicit/incompressible/test{\_}2p{\_}incompressible{\_}tpfa}. -\item Enter the folder \texttt{porousmediumflow/2p/implicit/incompressible}.\\ Type \texttt{make test{\_}2p{\_}incompressible{\_}tpfa} - in order to compile the application\\ \texttt{test{\_}2p{\_}incompressible{\_}tpfa}. To run the simulation, - type \texttt{./test{\_}2p{\_}incompressible{\_}tpfa} - into the console. If you explicitly want to state a parameter file, type\\ - \texttt{./test{\_}2p{\_}incompressible{\_}tpfa test\_2p.input}. - Adding \texttt{test\_2p.input} specifies that all - important parameters (like first timestep size, end of simulation and location +\item Enter the folder \texttt{porousmediumflow/2p/implicit/incompressible}.\\ Type \texttt{make test{\_}2p{\_}incompressible{\_}tpfa} + in order to compile the application\\\texttt{test{\_}2p{\_}incompressible{\_}tpfa}. To run the simulation, + type \texttt{./test{\_}2p{\_}incompressible{\_}tpfa params.input} + into the console. + The added \texttt{params.input} specifies that all + important run-time parameters (like first time step size, end of simulation and location of the grid file) can be found in a text file in the same directory with the - name \texttt{test\_2p.input}. -\item The simulation starts and produces some .vtu output files and also a .pvd - file. The .pvd file can be used to examine time series and summarizes the .vtu + name \texttt{params.input}. +\item The simulation starts and produces some VTU output files and also a PVD + file. The PVD file can be used to examine time series and summarizes the VTU files. It is possible to stop a running application by pressing $<$Ctrl$><$c$>$. \item You can display the results using the visualization tool ParaView (or alternatively VisIt). Just type \texttt{paraview} in the console and open the - .pvd file. On the left hand side, you can choose the desired parameter to be displayed. + PVD file. On the left hand side, you can choose the desired parameter to be displayed. \end{enumerate} -\subsection{Building Documentation} -\subsubsection{Doxygen} +\section{Building Documentation} +\label{sec:build-doc} +The building of included documentation like this handbook requires \LaTeX{} and auxiliary tools +\texttt{bibtex}. One usually chooses a \LaTeX{} distribution like \texttt{texlive} for this purpose. +It is possible to switch off the building of the documentation by setting the switch \texttt{--disable-documentation} +in the \texttt{CONFIGURE\_FLAGS} of the building options, see section \ref{buildIt}. + +\subsection{Doxygen} \label{sec:build-doxy-doc} -Doxygen documentation is done by especially formatted comments integrated in the source code, +Doxygen documentation is done by specifically formatted comments integrated in the source code, which can get extracted by the program \texttt{doxygen}. Beside extracting these comments, \texttt{doxygen} builds up a web-browsable code structure documentation like class hierarchy of code displayed as graphs, see \url{http://www.stack.nl/~dimitri/doxygen/}. -The Doxygen documentation of a module can be built, if \texttt{doxygen} is installed, -by running \texttt{dunecontrol}, entering the \texttt{build-*}directory, and execute +The Doxygen documentation of a module can be built if \texttt{doxygen} is installed, +by running \texttt{dunecontrol}, entering the \texttt{build-*}directory, and executing \texttt{make doc}. Then point your web browser to the file \texttt{MODULE\_BUILD\_DIRECTORY/doc/doxygen/html/index.html} to read the generated documentation. This should also work for other \Dune modules. -\subsubsection{Handbook} +\subsection{Handbook} To build the \Dumux handbook go into the \texttt{build-}directory and run \texttt{make doc} or \texttt{make 0\_dumux-handbook\_pdf}. The pdf can then be found in \texttt{MODULE\_BUILD\_DIRECTORY/doc/handbook/0\_dumux-handbook.pdf}. -\subsection{External Libraries and Modules} \label{sec:external-modules-libraries} +\section{External Libraries and Modules} \label{sec:external-modules-libraries} The libraries described below provide additional functionality but are not generally required to run \Dumux. -If you are going to use an external library check the information provided on the \Dune website% +If you are going to use an external library, check the information provided on the \Dune website% \footnote{DUNE: External libraries, \url{https://www.dune-project.org/doc/external-libraries/}}. -If you are going to use an external \Dune module the website on external modules% +If you are going to use an external \Dune module, the website on external modules% \footnote{DUNE: External modules, \url{https://www.dune-project.org/groups/external/}} can be helpful. @@ -251,7 +234,7 @@ Make sure that it uses the same library as \Dune when configuring the external l Some of the libraries are then compiled within that directory and are not installed in a different place, but \Dune may need to know their location. Thus, one may have to refer to -them as options for \texttt{dunecontrol}, for example via the options file \texttt{my-debug.opts}. +them as options for \texttt{dunecontrol}, for example via the options file \texttt{my-cmake.opts}. Make sure you compile the required external libraries before you run \texttt{dunecontrol}. An easy way to install some of the libraries and modules given below is the @@ -259,7 +242,7 @@ An easy way to install some of the libraries and modules given below is the has to be called from your common root directory. -\subsubsection{List of External Libraries and Modules} +\subsection{List of External Libraries and Modules} In the following list, you can find some external modules and external libraries, and some more libraries and tools which are prerequisites for their use. @@ -275,11 +258,24 @@ and some more libraries and tools which are prerequisites for their use. or network flow problems. Download: \url{https://gitlab.dune-project.org/extensions/dune-foamgrid} +\item \textbf{opm-grid}: opm-grid is a DUNE module supporting grids in a corner-point format. + Download: \url{https://github.com/OPM/opm-grid.git} + +\item \textbf{dune-subgrid}: The dune-subgrid module is a meta-grid implementation that allows +to mark elements of another hierarchical dune grid and use this sub-grid just like a regular grid. +The set of marked elements can then be accessed as a hierarchical dune grid in its own right. +Dune-Subgrid provides the full grid interface including adaptive mesh refinement. + Download: \url{https://git.imp.fu-berlin.de/agnumpde/dune-subgrid.git} + +\item \textbf{dune-spgrid}: The DUNE module dune-spgrid provides a structured, parallel grid +and supports periodic boundary conditions. + Download: \url{https://gitlab.dune-project.org/extensions/dune-spgrid.git} + \item \textbf{SuperLU}: External library for solving linear equations. SuperLU is a general purpose library for the direct solution of large, sparse, non-symmetric systems of linear equations. Download: \url{http://crd.lbl.gov/~xiaoye/SuperLU} -\item \textbf{UMFPack}: External library for solving linear equeations. It is part of SuiteSparse. +\item \textbf{UMFPack}: External library for solving linear equations. It is part of SuiteSparse. \item \textbf{dune-UG}: External library for use as grid. UG is a toolbox for unstructured grids, released under GPL. To build UG the tools \texttt{lex}/\texttt{yacc} or the GNU variants of \texttt{flex}/\texttt{bison} must be provided. @@ -302,5 +298,5 @@ depending on which modules of \Dune and which external libraries you use. \item \textbf{Compilers}: Beside \texttt{g++}, \Dune can be built with Clang from the LLVM project and Intel \Cplusplus compiler. C and Fortran compilers are needed for some external libraries. As code of - different compilers is linked together they have to be be compatible with each other. + different compilers is linked together, they have to be be compatible with each other. \end{itemize} diff --git a/doc/handbook/3_tutorial.tex b/doc/handbook/3_tutorial.tex deleted file mode 100644 index b31d3a39f357a5c524e26bd7c60d6b387a52cd49..0000000000000000000000000000000000000000 --- a/doc/handbook/3_tutorial.tex +++ /dev/null @@ -1,2 +0,0 @@ -The tutorial provides instructions ranging from how to set boundary conditions in \Dumux to how to set up your own \Dumux module. -Go to the directory \texttt{tutorial} in the \texttt{dumux} module and read the \texttt{README.md} (best to be opened in a web browser) for instructions on the tutorial. diff --git a/doc/handbook/4_course.tex b/doc/handbook/4_course.tex new file mode 100644 index 0000000000000000000000000000000000000000..c3dbee42f71ec5afc545bc5fa74d4bfe191c08c8 --- /dev/null +++ b/doc/handbook/4_course.tex @@ -0,0 +1,42 @@ +So, you've downloaded your very own copy of \Dumux and its dependencies. +You've run dunecontrol, and your example ``test$\_$dumux" not only compiles, +but it even shows a nice simulation in ParaView. +Maybe you've read through parts of the handbook, and even started looking +through the Doxygen documentation. +Well done. What now? \par +% +\textit{``How on earth is this going to help me solve my multi-(phase, component, +scale, physics) flow and transport problems in porous media systems?''}, you begin to wonder. +Don't panic! In order to best ease our prospective users and developers into the +wonderful \Dumux simulation environment, we've prepared a \Dumux course. +This course is offered once a year over a period of 3 days at the University of Stuttgart. +If you're looking for information on attending, subscribe to the \Dumux mailing list +and stay tuned for updates: +\url{https://listserv.uni-stuttgart.de/mailman/listinfo/dumux}. \par +% +\textit{``But the course won't take place for another 6 months!"} and, +\textit{``I want to start developing a numerical model of my challenging and + interesting process now!"}, you think. +Not a problem. The course materials are all shared online in their own +git repository. A series of beginner-level exercises are explained +such that you can see how a model is developed in \Dumux. As a teaser, we've + also included a suite of examples from hot topics we're working on. Models + exploring ``Coupling free flow and porous-media flow", ``Flow in fractured + porous media" and ``Fluid-solid phase change" are all introduced. \par + % +\textit{``Sounds great, but where is this material? I can't find it within +what I've downloaded."}, you question. +The \Dumux course material is available online: +\url{https://git.iws.uni-stuttgart.de/dumux-repositories/dumux-course}. \par +In order to download this repository, which acts as an additional module to +the \Dumux base, you can download an installation script with the following command: +\begin{lstlisting}[style=Bash] +$ wget https://git.iws.uni-stuttgart.de/dumux-repositories/dumux-course/raw/releases/3.0/scripts/install.sh +\end{lstlisting} +This script will install \texttt{dumux}, it's Dune dependencies, and the \texttt{dumux-course} +repository. Within the directory \texttt{dumux-course} there are a series of exercises +and slides describing the previously described examples. \par +% +The \Dumux course will be updated with each \Dumux release. +The above script will download the correct version (\textbf{releases/3.0}) of both +the \texttt{dumux} and \texttt{dumux-course} module. diff --git a/doc/handbook/4_externaltools.tex b/doc/handbook/4_externaltools.tex deleted file mode 100644 index 875b70559bea1eb67e4837c45f16cb1af699a5e5..0000000000000000000000000000000000000000 --- a/doc/handbook/4_externaltools.tex +++ /dev/null @@ -1,57 +0,0 @@ -\section{External Tools} -\label{sc_externaltools} - -\subsection{Eclipse} -There is an Eclipse style file which can be used for \Dumux. -\begin{enumerate} - \item open in eclipse: \texttt{Window} $\rightarrow$ \texttt{Preferences} $\rightarrow$ - \texttt{C/C++} $\rightarrow$ \texttt{Code Style} $\rightarrow$ \texttt{Formatter} - \item press the \texttt{Import} button - \item choose the file \texttt{eclipse\_profile.xml} from your dumux-devel directory - \item make sure that now \Dumux is chosen in \texttt{Select a profile} -\end{enumerate} - - -\subsection{Git} -Git is a version control tool which we use. -The basic Git commands are: -\begin{itemize} - \item \texttt{git checkout} receive a specified branch from the repository - \item \texttt{git clone} clone a repository; creates a local copy - \item \texttt{git diff} to see the actual changes compared to your last commit - \item \texttt{git pull} pull changes from the repository; synchronizes the - repository with your local copy - \item \texttt{git push} push comitted changes to the repository; synchronizes - your local copy with the repository - \item \texttt{git status} to check which files/folders have been changed - \item \texttt{git gui} graphical user interface, helps selecting changes for - a commit -\end{itemize} - - -\subsection{Gnuplot} -A gnuplot interface is available to plot or visualize results during a simulation run. -This is achieved with the help of the class provided in \texttt{io/gnuplotinterface.hh}. -Have a look at tests including this header for examples how to use this interface. - - -\subsection{Gstat} -Gstat is an open source software tool which generates geostatistical random fields (see \url{www.gstat.org}). -In order to use gstat, execute the \texttt{bin/installexternal.sh} from your \Dumux root -directory or donwload, unpack and install the tarball from the gstat-website. -Then rerun cmake (in the second case set \texttt{GSTAT\_ROOT} in your input file to the -path where gstat is installed). - - -\subsection{ParaView} -\paragraph{Reload Button:} -There are scripts to reload \texttt{*.pvd} or series of {\texttt{*.vtu} files since ParaView 4.2. -The scripts can be found -\href{http://markmail.org/message/exxynsgishbvtngg#query:+page:1+mid:rxlwxs7uqrfgibyv+state:results}{\texttt{under this link}}. -Just save the specific code portion in a file and load it via \texttt{Macros} $\rightarrow$ \texttt{Add new macro}. - -\paragraph{Guide:} -Since ParaView 4.3.1 The ParaView Guide is partly -available for free download, see \url{http://www.paraview.org/documentation/}. -It corresponds to the ParaView book, only without three application chapters. -Attention, its size is 180 MiB. diff --git a/doc/handbook/3_furtherpractice.tex b/doc/handbook/4_furtherpractice.tex similarity index 83% rename from doc/handbook/3_furtherpractice.tex rename to doc/handbook/4_furtherpractice.tex index dd9452aa940b81eb0934566d069cd824357b93ca..d31e227e73f23364c24f7a213110859fb817b96b 100644 --- a/doc/handbook/3_furtherpractice.tex +++ b/doc/handbook/4_furtherpractice.tex @@ -5,41 +5,38 @@ If there is a need for further practice, we refer here to the test problems that are already implemented in \Dumux. Several examples for all models can be found in the \texttt{test}-directory. An overview over the available test cases can be found in the class documentation \url{http://www.dumux.org/documentation.php}. -% There you also find a \emph{feature-list} for the individual tests.%TODO Another possibility to gain more experience with \Dumux is the \texttt{dumux-lecture} module -that contains different application examples that are used in the lectures at the +that contains different application examples that are used in the lectures at the Department of Hydromechanics and Modelling of Hydrosystems in Stuttgart. The \texttt{dumux-lecture} module can be obtained as follows: \begin{lstlisting}[style=Bash] $ git clone https://git.iws.uni-stuttgart.de/dumux-repositories/dumux-lecture.git \end{lstlisting} -% TODO: remove again as soon as invalid: -Note that \texttt{dumux-lecture} is currently only compatible with the \Dumux release 2.12. -The module is structured based on the different lectures: +The module is structured based on the different lectures: \begin{itemize} \item mm: Multiphase Modelling, \item efm: Environmental Fluid Mechanics, \item mhs: Modelling of Hydrosystems. \end{itemize} -The majority of applications is covered in the course Multiphase Modelling (mm), +The majority of applications is covered in the course Multiphase Modelling (mm), while there are also some basic examples from the -courses Environmental Fluid Mechanics (efm) and Modelling of Hydrosystems (mhs). +courses Environmental Fluid Mechanics (efm) and Modelling of Hydrosystems (mhs). These applications are primarily designed to enhance the understanding of conceptualizing the -governing physical processes and their implementation in a numerical simulator. -Different aspects of modelling multi-phase multi-component flow and transport processes are shown. -The lectures focus on questions like, e. g., the assignment of boundary conditions, the choice of the +governing physical processes and their implementation in a numerical simulator. +Different aspects of modeling multi-phase multi-component flow and transport processes are shown. +The lectures focus on questions like, e. g., the assignment of boundary conditions, the choice of the appropriate physics for a given problem (which phases, which components), discretization issues, time stepping. You can find, e. g., a comparison of different two-phase flow problems: The -more simple approach considers two immiscible fluids while components in both phases with interphase +more simple approach considers two immiscible fluids while components in both phases with inter-phase mass transfer are considered in the more complex approach. All scenarios and their physical background are explained in additional .tex-files, -which are provided in sub-directories named \texttt{description}. The following test cases are +which are provided in sub-directories named \texttt{description}. The following test cases are contained in the \texttt{dumux-lecture} module: \begin{itemize} \item \texttt{buckleyleverett}: The Buckley-Leverett Problem is a classical porous media flow show case -\item \texttt{co2plume}: Analysis of the influence of the gravitational number on the $\text{CO}_2$ plume +\item \texttt{co2plume}: Analysis of the influence of the gravitational number on the $\text{CO}_2$ plume \item \texttt{columnxylene}: A VEGAS experiment \item \texttt{convectivemixing}: A test case related to CO$_2$ storage \item \texttt{fuelcell}%TODO diff --git a/doc/handbook/4_guidelines.tex b/doc/handbook/4_guidelines.tex deleted file mode 100644 index aafaedfe13428b15b400bb6949fbf381a48179b8..0000000000000000000000000000000000000000 --- a/doc/handbook/4_guidelines.tex +++ /dev/null @@ -1,126 +0,0 @@ -\section{Coding Guidelines} -\label{sc_guidelines} -Writing code in a readable manner is very important, especially -for future code developers (e.g. for adding features, debugging, etc.). -This section is inspired by the DUNE coding guidelines -\url{https://www.dune-project.org/dev/codingstyle/}, which is strongly recommended. - -\subsection{Documentation:} -Please document freely what each part of your code \emph{should} do. All comments/documentation -is in English. -We proclaim the Doc-Me Dogma, which means whatever you do, please document -it at least with: -\begin{lstlisting}[style=DumuxCode] - \todo Please doc me! -\end{lstlisting} -That way at least the absence of documentation is documented, and it is easier -to get rid of it systematically. -In the following we will describe several ways for -commenting code in \Dumux.\\ -There are four ways to comment a \textbf{single line} of code: -\begin{lstlisting}[style=DumuxCode] -Line of code 1 // Short comment on line of code 1 that will not show in doxygen -Line of code 2 //!< Short comment on line of code 2 that will show in doxygen -//! Short comment on the following line (line of code 3) that will show in doxygen -Line of code 3 -/*! - * Longer comment on line of code 4 - * with several lines of length - * that will show in doxygen - */ -Line of code 4 -\end{lstlisting} -The third and fourth of the above shown options can also be used to document functions with -neither method parameters nor return value.\\ -For doxygen to be able to group the \textbf{files} correctly, please add before the headerguard: -\begin{lstlisting}[style=DumuxCode] -/*! - * \file - * \ingroup GroupName - * \brief A short description of the file. - */ - -#ifndef HEADERGUARD -#define HEADERGUARD -\end{lstlisting} -For doxygen to be able to group the \textbf{classes} correctly, please add before each class: -\begin{lstlisting}[style=DumuxCode] -/*! - * \ingroup GroupName - * \brief A short description of the class. - * - * Optional detailed description of the class - * over several lines. - */ -template -\end{lstlisting} -For an overview over all available groups and to add new groups please -see the file\\ \texttt{doc/doxygen/modules.txt} from the \texttt{dumux} module.\\ -Please add before each \textbf{function} with method parameters or return value: -\begin{lstlisting}[style=DumuxCode] -/*! - * \brief A short description of the function. - * - * Optional detailed description of the function - * over several lines. - * - * \param paramName Very short description of paramName - * \return returnName Very short description of returnName - */ -paramType functionName(paramType paramName) -{ - ... - return returnName -} -\end{lstlisting} -Furthermore, please comment \textit{all}: -\begin{itemize} - \item Template Parameters - \item Exceptions thrown by a method - \item Method parameters which are not self-explanatory should always - have a meaningful comment at calling sites. Example: - \begin{lstlisting}[style=DumuxCode] - localResidual.eval(/*includeBoundaries=*/true); - \end{lstlisting} -\end{itemize} - -\subsection{Naming:} -To avoid duplicated types or variables and for a better understanding and usability -of the code we have the following naming conventions: -\begin{itemize} -\item \textbf{Variables/Functions \ldots} - \begin{itemize} - \item start in \emph{lower} case and contain letters. - \item \emph{CamelCase}: if the name consists of several words, then - the first letter of a new word is capital. - \item \emph{Self-Explaining}: in general abbreviations should be avoided (write saturation in stead of S) - \item \emph{Abbreviations}: If and only if a single letter that represents an - abbreviation or index is followed by a single letter (abbreviation or index), - CamelCase is \textbf{not} used. An inner-word underscore is only permitted if - it symbolizes a fraction line. Afterwards, we continue with lower case, i.e. - the common rules apply to both enumerator and denominator. Examples: - \begin{itemize} - \item \texttt{pw} but \texttt{pressureW} $\rightarrow$ because ``pressure'' is a word. - \item \texttt{srnw} but \texttt{sReg} $\rightarrow$ because ``reg'' is not an - abbreviation of a single letter. ``n'' abbreviates ``non'', - ``w'' is ``wetting'', so not CamelCase. - \item \texttt{pcgw} but \texttt{dTauDPi} $\rightarrow$ Both ``Tau'' and ``Pi'' - are words, plus longer than a letter. - \item \textbf{But:} \texttt{CaCO3} The only exception: chemical formulas are - written in their chemically correct way $\rightarrow$ \texttt{CaCO3} - \end{itemize} - \end{itemize} -\item \textbf{Private Data Variables:} Names of private data variables end with an - underscore and are the only variables that contain underscores. -\item \textbf{Type names:} For type names, the same rules as for variables apply. The - only difference is that the \emph{first letter is capital}. -\item \textbf{Files:} File names should consist of \emph{lower case} letters - exclusively. Header files get the suffix \texttt{.hh}, implementation files the - suffix \texttt{.cc} -\item \textbf{The Exclusive-Access Macro:} Every header file traditionally begins - with the definition of a preprocessor constant that is used to make sure that - each header file is only included once. If your header file is called - 'myheaderfile.hh', this constant should be DUMUX\_MYHEADERFILE\_HH. -\item \textbf{Macros:} The use of preprocessor macros is strongly discouraged. If you - have to use them for whatever reason, please use capital letters only. -\end{itemize} diff --git a/doc/handbook/4_newfoldersetup.tex b/doc/handbook/4_newfoldersetup.tex deleted file mode 100644 index c1700cd9a09937afa0048f9c1de08b201208c2bb..0000000000000000000000000000000000000000 --- a/doc/handbook/4_newfoldersetup.tex +++ /dev/null @@ -1,24 +0,0 @@ -\section{Setup of new Folders and new Tests} -\label{sc_newfoldersetup} -This section describes how to set up a new folder and how to tell -the build system there is a new one. -\paragraph{Adding new Folders} -\begin{enumerate}[1)] - \item create new folder with content - \item adapt the \verb+CMakeList.txt+ in the folder above and add a line with - \verb+add_subdirectory(NEW_FOLDER)+ - \item create a \verb+CMakeList.txt+ in the newly created folder - \item go to your \texttt{build}-directory and type \verb+make+ to - re-configure the system -\end{enumerate} - -\paragraph{Adding new Test Programs} -\noindent To add a test use the \texttt{add\_dumux\_test} macro. -The command has four arguments: -\begin{enumerate}[1)] - \item name of test (has to be unique) - \item name of executable - \item source file (*.cc) - \item command to be executed as test - either the executable or a - some helper script with arguments -\end{enumerate} diff --git a/doc/handbook/4_restartsimulations.tex b/doc/handbook/4_restartsimulations.tex deleted file mode 100644 index 30ce43199130c08f732e92fc3fff16ff43d8272e..0000000000000000000000000000000000000000 --- a/doc/handbook/4_restartsimulations.tex +++ /dev/null @@ -1,26 +0,0 @@ -\section{Restart \Dumux Simulations} -\label{sc_restartsimulations} -Restart is currently not available in the \DumuxVersion~release. We are working on it! - -% You can restart the simulation -% from a specific point in time or extend the simulation beyond the originally -% end of simulation. What you need is a \texttt{*.drs} file (which contains the -% all necessary restart information. -% Then you can simply restart a simulation via -% \begin{lstlisting}[style=Bash] -% ./test_program -TimeManager.Restart RESTART_TIME -% \end{lstlisting} -% To test restart behavior, use the \texttt{test\_box1p2cni} problem -% in the \texttt{test/implicit/1p2c} folder. -% You get the \texttt{RESTART\_TIME} from the name of your \texttt{.drs} file. -% Restarting will only work when the exact time from an existing restart file is given. -% If you need more restart files, you can change the frequency -% by including the function into your problem: -% \begin{lstlisting}[style=DumuxCode] -% // Writes a restart file every 5th time step -% bool shouldWriteRestartFile() const -% { -% return (this->timeManager().timeStepIndex() % 5 == 0); -% } -% \end{lstlisting} - diff --git a/doc/handbook/4_assemblinglinearsystem.tex b/doc/handbook/5_assemblinglinearsystem.tex similarity index 89% rename from doc/handbook/4_assemblinglinearsystem.tex rename to doc/handbook/5_assemblinglinearsystem.tex index 8268e39155f92b257e5c97f968b194780d6462bc..e05dad50ab5ad89acc3a9109a6f53a450fbd71ef 100644 --- a/doc/handbook/4_assemblinglinearsystem.tex +++ b/doc/handbook/5_assemblinglinearsystem.tex @@ -50,8 +50,8 @@ direction of maximum growth $\textbf{x}^i$ until our approximated solution becom \subsection{Structure of matrix and vectors} To understand the meaning of an entry in the matrix or the vector of the linear system, we have to define their structure. Both have a blocking structure. Each block contains the degrees of -freedom (also called variable or unknown) for a sub-control volume. The equation index is used -to order of the degrees of freedom. For each sub-control volume we have one block. The mapper is +freedom (also called variable or unknown) for a control volume. The equation index is used +to order of the degrees of freedom. For each control volume we have one block. The mapper is used to order the blocks. \begin{figure}[htbp] @@ -59,23 +59,23 @@ used to order the blocks. \begin{tikzpicture}[fill=dumuxBlue] %% blocking structure % matrix - \node at (0.3,4.2){\footnotesize 1. SCV}; - \node at (1.7,4.2){\footnotesize 2. SCV}; - \node at (3.5,4.2){\footnotesize $n$. SCV}; + \node at (0.3,4.2){\footnotesize 1. CV}; + \node at (1.7,4.2){\footnotesize 2. CV}; + \node at (3.5,4.2){\footnotesize $n$. CV}; \draw (0,0) rectangle (4,4); - + \fill (0.1,3.1) rectangle (0.9,3.9); \fill (1.1,3.1) rectangle (1.9,3.9); \node at (2.5,3.5) {$\dots$}; \fill (3.1,3.1) rectangle (3.9,3.9); - \node at (4,3.5) [right]{\footnotesize 1. SCV}; + \node at (4,3.5) [right]{\footnotesize 1. CV}; \fill (0.1,2.1) rectangle (0.9,2.9); \fill (1.1,2.1) rectangle (1.9,2.9); \node at (2.5,2.5) {$\dots$}; \fill (3.1,2.1) rectangle (3.9,2.9); - \node at (4,2.5) [right]{\footnotesize 2. SCV}; + \node at (4,2.5) [right]{\footnotesize 2. CV}; \node at (0.5,1.5) {$\vdots$}; \node at (1.5,1.5) {$\vdots$}; @@ -86,7 +86,7 @@ used to order the blocks. \fill (1.1,0.1) rectangle (1.9,0.9); \node at (2.5,0.5) {$\dots$}; \fill (3.1,0.1) rectangle (3.9,0.9); - \node at (4,0.5) [right]{\footnotesize $n$. SCV}; + \node at (4,0.5) [right]{\footnotesize $n$. CV}; % vector \draw (5.5,0) rectangle (5.9,4); @@ -94,19 +94,19 @@ used to order the blocks. \fill (5.6,2.1) rectangle (5.8,2.9); \node at (5.7,1.5) {$\vdots$}; \fill (5.6,0.1) rectangle (5.8,0.9); - + %% intra-block structure \fill (8.1,2.1) rectangle (8.9,2.9); \draw (9,2.8) -- (9.6,3.4); \draw (9,2.6) -- (9.6,2.8); \draw (9,2.2) -- (9.3,1.6); - + \node at (10,4) {${eqIdx}$}; \node at (10,3.4) {$0$}; \node at (10,2.8) {$1$}; \node at (10,2.2) {$\vdots$}; \node at (10,1.6) {$m-1$}; - + \fill (11.1,2.1) rectangle (11.3,2.9); \draw (11,2.8) -- (10.4,3.4); \draw (11,2.6) -- (10.4,2.8); diff --git a/doc/handbook/4_developingdumux.tex b/doc/handbook/5_developingdumux.tex similarity index 76% rename from doc/handbook/4_developingdumux.tex rename to doc/handbook/5_developingdumux.tex index e5c02ee1cbc6174a20b4d876f7b8d02aed99365b..2ad63f31b0c387a05f7a04b697a823186d3661a4 100644 --- a/doc/handbook/4_developingdumux.tex +++ b/doc/handbook/5_developingdumux.tex @@ -5,7 +5,7 @@ \paragraph{Issues and Bug Tracking} The bug-tracking system \emph{GitLab Issues} offers the possibility to report bugs or discuss new development requests. -Feel free to register (if you don't have a \emph{Git} account already) and to constribute +Feel free to register (if you don't have a \emph{Git} account already) and to contribute at \url{https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/issues}. \paragraph{Commits, Merges, etc.} @@ -25,27 +25,29 @@ You can subscribe to the mailing list via \url{https://listserv.uni-stuttgart.de/mailman/listinfo/dumux}, then you will be informed about upcoming releases or events. +\subsection{Coding Guidelines} +Writing code in a readable manner is very important, especially +for future code developers (e.g. for adding features, debugging, etc.). +For the style guide and instructions how to contribute to \Dumux visit +\url{https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/blob/master/CONTRIBUTING.md}. + + \subsection{Tips and Tricks} \Dumux users and developers at the LH2 are also referred to the internal Wiki for more information. -\paragraph{Option Files optim.opts and debug.opts} +\paragraph{Optimized computation vs debugging} \Dune and \Dumux are built with the help of \texttt{dunecontrol}, as explained on page \pageref{buildIt}. -The options needed to be specified for that are provided using option files like -\texttt{debug.opts} and \texttt{optim.opts}. These two compile \Dune and \Dumux -either for debugging or for fast simulation. Programs compiled with optimization options -can lead to a speedup of factor up to ten!\\ -In contrast programs that are compiled with optimization can hardly be debugged. -You can modify the files and change the compiler, the name of the build director, -add third-party dependencies, add additional compiler flags, ... . +Per default, \Dumux is compiled using optimization options, which leads to faster runtimes but is unsuitable +for debugging. For debug opts you can set \texttt{DCMAKE\textunderscore BUILD\textunderscore TYPE} to \texttt{Debug} or \texttt{RelWithDebInfo} +in your options file. You can also do this in any of the \texttt{CMakeLists.txt} in Dumux by adding: + \begin{lstlisting}[style=Shell] -BUILDDIR=build-clang -CMAKE_FLAGS="\ - -DCMAKE_C_COMPILER=/usr/bin/clang \ - -DCMAKE_CXX_COMPILER=/usr/bin/clang++ \ - -DUG_DIR=./externals/ug-3.12.1" +set(CMAKE_BUILD_TYPE Debug) \end{lstlisting} +Afterwards rerun cmake again (run cmake ). + \paragraph{Dunecontrol for selected modules} A complete build using \texttt{dunecontrol} takes some time. In many cases not all modules need to be re-built. Pass the flag \texttt{--only=dumux} to \texttt{dunecontrol} for configuring or building only \Dumux. A more @@ -64,7 +66,10 @@ To apply a patch in the same directory type: \begin{lstlisting}[style=Bash] $ patch -p1 < PATCHFILE \end{lstlisting} -See \ref{sc:patchingDUNE} if you need to apply patches to \Dumux or \Dune. + +%TODO: currently, no DUNE patches necessary! Thus, this section is commented and the missing refrence would be bad. +% Uncomment the following statement again when patches might be necessary. +% See \ref{sc:patchingDUNE} if you need to apply patches to \Dumux or \Dune. \paragraph{File Name and Line Number by Predefined Macro} If you want to know where some output or debug information came from, use the predefined @@ -98,9 +103,3 @@ To check one header file for all necessary includes to compile the contained cod Include the option \texttt{-DENABLE\_HEADERCHECK=1} in your opts file and run \texttt{dunecontrol}. Then go to the top level in your build-directory and type \texttt{make headercheck} to check all headers or press 'tab' to use the auto-completion to search for a specific header. - -\paragraph{Naming conventions} -General guidelines for naming conventions are specified in Section \ref{sc_guidelines}. -However, in order to avoid ambiguity a list of proposed names for variables, types, -functions etc is provided where users and mainly \Dumux developers can refer for -standards (check \texttt{dumux-devel/\allowbreak doc/\allowbreak naminglist/\allowbreak naming-conventions.odt}). diff --git a/doc/handbook/5_externaltools.tex b/doc/handbook/5_externaltools.tex new file mode 100644 index 0000000000000000000000000000000000000000..dee059dc1dc7e5cd04d17b3f4f7f5986a7ce61e7 --- /dev/null +++ b/doc/handbook/5_externaltools.tex @@ -0,0 +1,79 @@ +\section{External Tools} +\label{sc_externaltools} + +\subsection{Git} +Git is a version control tool which we use. +The basic Git commands are: +\begin{itemize} + \item \texttt{git checkout}: receive a specified branch from the repository + \item \texttt{git clone}: clone a repository; creates a local copy + \item \texttt{git diff}: to see the actual changes compared to your last commit + \item \texttt{git pull}: pull changes from the repository; synchronizes the + repository with your local copy + \item \texttt{git push}: push comitted changes to the repository; synchronizes + your local copy with the repository + \item \texttt{git status}: to check which files/folders have been changed + \item \texttt{git gui}: graphical user interface, helps selecting changes for + a commit +\end{itemize} + + +\subsection{Gnuplot} +\label{gnuplot} +A gnuplot interface is available to plot or visualize results during a simulation run. +This is achieved with the help of the \texttt{Dumux::GnuplotInterface} class provided in \texttt{io/gnuplotinterface.hh}. + +To use the gnuplot interface you have to make some modifications in your file, e.g., your main file. + +First, you have to include the corresponding header file for the gnuplot interface. +\begin{lstlisting}[style=DumuxCode] +#include gnuplot; +\end{lstlisting} + +As an example, to plot the mole fraction of nitrogen (\texttt{y}) over time (\texttt{x}), +extract the variables after each time step in the time loop. +The actual plotting is done using the method of the gnuplot interface: + +\begin{lstlisting}[style=DumuxCode] +gnuplot.resetPlot(); // reset the plot +gnuplot.setXRange(0.0, 72000.0); // specify xmin and xmax +gnuplot.setYRange(0.0, 1.0); // specify ymin and ymax +gnuplot.setXlabel("time [s]"); // set xlabel +gnuplot.setYlabel("mole fraction mol/mol"); // set ylabel + +// set x-values, y-values, the name of the data file and the Gnuplot options +gnuplot.addDataSetToPlot(x, y, "N2.dat", options); + +gnuplot.plot("mole_fraction_N2"); // set the name of the output file +\end{lstlisting} + +It is also possible to add several data sets to one plot by calling \texttt{addDataSetToPlot()} more than once. +For more information have a look into a test including the gnuplot interface header file, the doxygen documentation +of \texttt{Dumux::GnuplotInterface}, or the header file itself (\texttt{dumux/io/gnuplotinterface.hh}). + + +\subsection{Gstat} +Gstat is an open source software tool which generates geostatistical random fields (see \url{www.gstat.org}). +In order to use gstat, execute the \texttt{bin/installexternal.sh} from your \Dumux root +directory or donwload, unpack and install the tarball from the gstat-website. +Then rerun cmake (in the second case set \texttt{GSTAT\_ROOT} in your input file to the +path where gstat is installed). + + +\subsection{ParaView} +\paragraph{Reload Button:} +There are scripts to reload PVD or series of VTU files since ParaView 4.2. +The scripts can be found +\href{http://markmail.org/message/exxynsgishbvtngg#query:+page:1+mid:rxlwxs7uqrfgibyv+state:results}{\texttt{under this link}}. +Just save the specific code portion in a file and load it via \texttt{Macros} $\rightarrow$ \texttt{Add new macro}. + +\paragraph{Guide:} +Since ParaView 4.3.1, The ParaView Guide is partly +available for free download, see \url{http://www.paraview.org/documentation/}. +It corresponds to the ParaView book, only three application chapters short. +Attention, its size is 180 MiB. diff --git a/doc/handbook/5_grids.tex b/doc/handbook/5_grids.tex deleted file mode 100644 index aaad10db862fd27761bcd521b3b5fbfdd3ee025b..0000000000000000000000000000000000000000 --- a/doc/handbook/5_grids.tex +++ /dev/null @@ -1,137 +0,0 @@ -\section{Grid Handling} -\label{sec:gridhandling} - -This section summarizes some ideas about grid generation and grid formats that can be used by \Dumux. In general, -\Dumux can read grids from file, or, construct grids inside the code. All grids are constructed inside a so called \texttt{GridCreator} which is a \Dumux property. -Note that some \texttt{GridCreator}s are already available in \Dumux, so e.g. -construction of a structured grid is fairly easy. We will subsequently introduce the supported file formats, the standard grid creator and its capabilities, -and briefly mention how to customize and deal with common other grid formats. - -\subsection{Supported file formats} -\Dumux can read grids from file using the Dune Grid Format (DGF) or the Gmsh mesh format. - -\subsubsection{Dune Grid Format} -Most of our \Dumux tests and tutorials use the Dune Grid Format (DGF) to read in grids. A detailed description -of the DGF format and some examples can be found in the \Dune doxygen documentation -\textbf{(Modules $\rightarrow$ I/O $\rightarrow$ Dune Grid Format (DGF)}). To generate larger or more -complex DGF files, we recommend to write your own scripts, e.g in \Cplusplus, Matlab or Python. - -The DGF format can also used to read in spatial parameters defined on the grid. These parameters can -be defined on nodes as well as on the elements. An example for predefined parameters on a grid -can be found in the \texttt{dumux/test/porousmediumflow/co2/implicit/} folder. - -\subsubsection{Gmsh Mesh Format} -Gmsh is an open-source flexible grid generator for unstructured finite-element meshes (\cite{GEUZAINE2009}, \url{http://geuz.org/gmsh/}). -\Dumux supports the default Gmsh mesh format (MSH). For the format specifics and how to create grids with Gmsh, e.g. using -the provided GUI, we refer to the Gmsh documentation (\url{http://geuz.org/gmsh/doc/texinfo/gmsh.html}). - -The MSH format can contain element and boundary markers defined in the grid. Thus, boundaries can be easily marked as e.g. inflow boundaries -using Gmsh. Further, the format supports higher order elements. They can be used to create boundary parameterization supported by e.g. the grid -manager \texttt{UGGrid}. -An example can be found in \texttt{dumux/test\allowbreak/io/gridcreator}. - - - -\subsection{The default \texttt{GridCreator}} -The default \texttt{GridCreator} is called \texttt{GridCreator} and is automatically avaible in all problems. -It can construct grids from a DGF file (*.dgf) by simply providing the filename to the grid in the \texttt{Grid} group~\footnote{Note -that group name \texttt{Grid} is the default group name and can be customized in your problem changing the string property \texttt{GridParameterGroup}. -This way it is possible, e.g. for problems with more than one grid, to set different group names for each grid, thus configuring them separately.} -of the input file: -\begin{lstlisting}[style=DumuxParameterFile] -[Grid] -File = mydgfgrid.dgf -\end{lstlisting} -If you are using an unstructured grid manager like \texttt{UGGrid} or \texttt{ALUGrid}, constructing a grid from a Gmsh mesh file (*.msh) is just changing a line: -\begin{lstlisting}[style=DumuxParameterFile] -[Grid] -File = mygmshgrid.msh -\end{lstlisting} -\Dumux will tell you in case your selected grid manager does not support reading Gmsh files. You want to intially refine your grid? It's just adding a line: -\begin{lstlisting}[style=DumuxParameterFile] -[Grid] -File = mydgfgrid.dgf -Refinement = 4 -\end{lstlisting} -When reading a Gmsh file, further parameters are recognized. \texttt{Verbose} enables verbose output on grid construction when set to $1$. -\texttt{BoundarySegments} enables reading parametrized boundaries. \texttt{PhysicalEntities} enables reading boundary and element flags. - -\subsubsection{Grid manager specific parameters} -The default \texttt{GridCreator} supports also a selection of grid specific parameters. -To give an example we look at the commonly used unstructured grid manager \texttt{UGGrid}. -\texttt{UGGrid}s support red-green refinement per default. One can turn off the green closure by setting the grid's closure type -\begin{lstlisting}[style=DumuxParameterFile] -[Grid] -File = mydgfgrid.dgf -ClosureType = None # or Green -\end{lstlisting} -For all available parameters see the Doxygen documentation. - -\subsubsection{Structured grids} -If you want to construct a structured grid with the default grid creator instead of the \texttt{File} key supply -\begin{lstlisting}[style=DumuxParameterFile] -[Grid] -LowerLeft = 0 0 0 -UpperRight = 1 1 1 -Cells = 10 10 20 -\end{lstlisting} -where \texttt{LowerLeft} is a vector to the lower left corner of the grid and \texttt{UpperRight} a vector to the upper right corner. -\texttt{Cells} is a vector with the number of cells in each coordinate direction. Note that for a grid in a two-dimensional world, the -vectors only have two entries. - -Depending on the grid manager further parameters are recognized. -\texttt{UGGrid}s, for example, supports simplex elements as well as hexahedral elements -(called simplified ``cube'' in \Dune). When creating a structured grid, we can select the cell type as follows -\begin{lstlisting}[style=DumuxParameterFile] -[Grid] -LowerLeft = 0 0 0 -UpperRight = 1 1 1 -Cells = 10 10 20 -CellType = Cube # or Simplex -\end{lstlisting} -For all available parameters see the Doxygen documentation. - -\subsection{Other grid formats and customized grid creators} -Other grid formats than DGF and MSH have to be converted to DGF or MSH to be read into \Dumux. A second possiblity (advanced \Cplusplus) is to write your own -\texttt{GridCreator}. -A (non-comprehensive) list of hints for some other common grid formats follows. - -\subsubsection{Petrel} -Grids from Petrel (in ASCII format with the extension *.GRDECL) can be imported into \Dumux in two ways: - \begin{enumerate} - \item Using the GRDECL format directly with the help of the grid-manager \texttt{dune-cornerpoint}. - \item Converting the GRDECL file into the DGF format. - \end{enumerate} -The fist options requires the installation of \texttt{dune-cornerpoint} along with its dependencies. Set the property \texttt{Grid} to \texttt{Dune::CpGrid} in your problem file. - -The second option has the advantage that you end up with a DGF which can then be used with any grid-manager (\texttt{dune-alugrid}, \texttt{UG} etc.) You also have to install \texttt{dune-cornerpoint}. Additionally you have to modify the converter \texttt{grdecl2vtu} found in \texttt{dune-cornerpoint/examples} to also write a DGF. To do so you have to: -\begin{itemize} - \item Include the \texttt{dgfwriter.hh} found in \texttt{dune-grid/dune/grid/io/file/dgfparser} - \item Create an object of the \texttt{Dune::DGFWriter} and call the its function \texttt{write()} within the \texttt{main} function for example after the \texttt{vtkwriter()} is called: -\begin{lstlisting}[style=DumuxCode] -Dune::DGFWriterParam dgfWriter(grid.leafView())) -dgfWriter.write(fnamebase + ".dgf") -\end{lstlisting} -\end{itemize} -Material parameters for elements with Petrel specific keywords like \texttt{PORO} are parsed by the converter \texttt{grdecl2vtu} (see the \texttt{main} function). They are available as vectors within the \texttt{main} function. The main GRDECL file with the coordinates must include the GRDECL files of the parameters, if for example the parameters are not already included, include the file bearing your parameter in your main GRDECL file: -\begin{lstlisting} -INCLUDE -'PARAMETER_X.GRDECL' -/ -\end{lstlisting} -To add the parameters to your DGF you have to make changes to the header \texttt{dgfwriter.hh} such that they are passed as arguments of the \texttt{write()} function and written after each element (modify \texttt{writeElement()} and internal \texttt{write()} functions accordingly). Take caution that you stick to the correct DGF syntax (see \textbf{Modules $\rightarrow$ I/O $\rightarrow$ Dune Grid Format (DGF)} for reference). - -\subsubsection{ArtMesh} -\href{http://www.topologica.org/toplog/wp/}{ArtMesh} is a 3D mesh generation software. It has its own mesh file format -which can be read by \Dumux via the \texttt{ArtGridCreator}. Traditionally it was used within \Dumux for fracture simulations with -the discrete fracture matrix model (\texttt{2pdfm}). A detailed description of the fracture network creation and gridding -can be found for example in \cite{Tatomir2012a}, pp. 68. - -\subsubsection{ICEM} -For complex geometries a graphical tool to create grids might be appropriate. One possibility to mesh for example CAD -geometry data is the commercial software \href{http://www.ansys.com/Products/Other+Products/ANSYS+ICEM+CFD/}{ANSYS ICEM -CFD}. A very detailed, but outdated description can be found at the LH2 internal wiki. A more recent best practice guide is available -in dumux-devel at dumux-devel/util/gridconverters/Documentation\_ICEM\_CFD\_create\_mesh.odt. At LH2 exists a script which converts the ICEM mesh into the DGF. - -% \subsubsection{Cornerpoint grids} -% TODO diff --git a/doc/handbook/5_newfoldersetup.tex b/doc/handbook/5_newfoldersetup.tex new file mode 100644 index 0000000000000000000000000000000000000000..ea26767b48355992a5353f51c5ee095db4eb67a1 --- /dev/null +++ b/doc/handbook/5_newfoldersetup.tex @@ -0,0 +1,27 @@ +\section{Setup of new Folders and new Tests} +\label{sc_newfoldersetup} +This section describes how to set up a new folder and how to tell +the build system there is a new one. +\paragraph{Adding new Folders} +\begin{enumerate}[1)] + \item create new folder with content + \item adapt the \verb+CMakeList.txt+ in the folder above and add a line with + \verb+add_subdirectory(NEW_FOLDER)+ + \item create a \verb+CMakeList.txt+ in the newly created folder + \item go to your \texttt{build}-directory and type \verb+make+ to + re-configure the system +\end{enumerate} + +\paragraph{Adding new Test Programs} +\noindent To add a test use the \texttt{add\_dune\_test} macro within the \texttt{CMakeList.txt} file. +The macro can be used with a variable amount of arguments. A simple call could look like this: + +\begin{lstlisting}[style=DumuxCode] +dune_add_test(NAME my_test + SOURCES main.cc + CMD_ARGS my_test params.input) +\end{lstlisting} + +Here, we create an executable called \texttt{my\_test} from a source file \texttt{main.cc}. +The name of the test will also be \texttt{my\_test} (has to be unique). The last argument specifies a command - here, we just run the executable \texttt{my\_test} with an input file \texttt{params.input}. For more advanced uses of +the \texttt{add\_dune\_test} macro, have a look at the \texttt{test} directory. A complete documentation is given under \url{https://www.dune-project.org/sphinx/core-2.5/}. diff --git a/doc/handbook/4_parameterfiles.tex b/doc/handbook/5_parameterfiles.tex similarity index 59% rename from doc/handbook/4_parameterfiles.tex rename to doc/handbook/5_parameterfiles.tex index df325e477a878c6592c4cfdfd58dcdacdd9bb5eb..f6f615891ed7a405f7e41064ea98daf5bb1e00c2 100644 --- a/doc/handbook/4_parameterfiles.tex +++ b/doc/handbook/5_parameterfiles.tex @@ -5,14 +5,14 @@ A list of all available parameters is provided in the Doxygen documentation: \te After having run the example application from section \ref{quick-start-guide} you will get the following output at the end of the simulation run -\footnote{If you did not get the output, restart the application the following way: -\texttt{./test{\_}2p{\_}incompressible{\_}tpfa test{\_}2p.input -PrintParameters true}, -this will print the parameters once your simulation is finished}: +\footnote{If you did not get the output, add \texttt{Parameters::print();} to your main file.}: \begin{lstlisting}[style=Bash] # Runtime-specified parameters used: [ Grid ] Cells = "48 32" UpperRight = "6 4" +[ Newton ] +EnablePartialReassembly = "true" [ Problem ] EnableGravity = "true" Name = "2p" @@ -23,9 +23,10 @@ LensUpperRight = "4.0 3.0" DtInitial = "250" TEnd = "3000" -# Default parameters used: -[ Implicit ] +# Global default parameters used: +[ Assembly ] NumericDifferenceMethod = "1" +[ Flux ] UpwindWeight = "1.0" [ LinearSolver ] MaxIterations = "250" @@ -35,6 +36,7 @@ ResidualReduction = "1e-13" Verbosity = "0" [ Newton ] EnableAbsoluteResidualCriterion = "false" +EnableChop = "false" EnableResidualCriterion = "false" EnableShiftCriterion = "true" MaxAbsoluteResidual = "1e-5" @@ -45,7 +47,6 @@ SatisfyResidualAndShiftCriterion = "false" TargetSteps = "10" UseLineSearch = "false" [ TimeLoop ] -MaxTimeStepDivisions = "10" MaxTimeStepSize = "1e300" [ Vtk ] AddProcessRank = "true" @@ -64,20 +65,33 @@ A number of things can be learned: \subsection{Parameter Values} -If you want to get the value of a parameter please use: +To get the value of an input parameter please use: \begin{lstlisting}[name=propsyscars,style=DumuxCode] -paramname_ = getParam("GROUPNAME.PARAMNAME"); +static const TYPE paramname = getParam("GROUPNAME.PARAMNAME"); \end{lstlisting} If you also want to set a default value for a parameter, just add it like this: \begin{lstlisting}[name=propsyscars,style=DumuxCode] -paramname_ = getParam("GROUPNAME.PARAMNAME", default); +static const TYPE paramname = getParam("GROUPNAME.PARAMNAME", default); +\end{lstlisting} + +As this function call is relatively expensive, the respective variables should always be \texttt{static} (e.g., if used in a loop). When dealing with multiple group names, e.g., in the context of coupled models, the fowolling methods might be more convenient: + +\begin{lstlisting}[name=propsyscars,style=DumuxCode] +auto modelParamGroup0 = "Model0"; +static const TYPE paramname0 = getParamFromGroup(modelParamGroup0, "GROUPNAME.PARAMNAME"); +auto modelParamGroup1 = "Model1"; +static const TYPE paramname1 = getParamFromGroup(modelParamGroup1, "GROUPNAME.PARAMNAME"); \end{lstlisting} -For further information you can also look at the \Dumux tutorial, especially exercise 1. +The \texttt{FVProblem} class provides a convenience function \texttt{paramGroup()}. + +The parameters can then be specified in the input file: -All applications have a help message which you can read by giving -\texttt{--help} as a command line argument to the application. -For further details, please have a look at \texttt{Dune::ParameterTree} -in the \Dune documentation. +\begin{lstlisting}[style=Bash] +[ Model0.Grid ] +File = file0.dgf +[ Model1.Grid ] +File = file1.dgf +\end{lstlisting} diff --git a/doc/handbook/5_propertysystem.tex b/doc/handbook/5_propertysystem.tex deleted file mode 100644 index e66b20aae04d9a004962bdee90234a1e4820235c..0000000000000000000000000000000000000000 --- a/doc/handbook/5_propertysystem.tex +++ /dev/null @@ -1,387 +0,0 @@ -\section{Property System} -\label{sec:propertysystem} -A high level overview over the property system's design and principle ideas -are given, then follows a reference and a self-contained example. - -\subsection{Motivation and features} -The \Dumux property system was designed as an attempt to mitigate the -problems of traits classes. It can be seen as a traits system -which allows easy inheritance and any acyclic dependency of parameter -definitions. Just like traits, the \Dumux property system is a compile -time mechanism, thus there is no run-time performance penalty associated -with it. - -In the context of the \Dumux property system, a property is an arbitrary -class body which may contain type definitions, values and methods. Each -property has a so-called \emph{property tag} which labels its name. - -Just like normal classes, properties can be arranged in hierarchies. In -the context of the \Dumux property system, nodes of the inheritance -hierarchy are called \emph{type tags}. - -It also supports \emph{property nesting} and -\emph{introspection}. Property nesting means that the definition of -a property can depend on the value of other properties which may be -defined for arbitrary levels of the inheritance hierarchy. The term -introspection denotes the ability to generate diagnostic messages -which can be used to find out where a certain property was defined and -how it was inherited. - -\subsection{How-to} -All source files which use the property system should include -the header file \path{dumux/common/propertysystem.hh}. -Declaration of type tags and -property tags as well as defining properties must be done inside the -namespace \texttt{Dumux::Properties}. - -\subsubsection{Defining Type Tags} -New nodes in the type tag hierarchy can be defined using -\begin{lstlisting}[style=DumuxCode] -NEW_TYPE_TAG(NewTypeTagName, INHERITS_FROM(BaseTagName1, BaseTagName2, ...)); -\end{lstlisting} -where the \texttt{INHERITS\_FROM} part is optional. To avoid -inconsistencies in the hierarchy, each type tag may be defined only -once for a program. - -\vskip1ex\noindent -Example: -\begin{lstlisting}[style=DumuxCode] -namespace Dumux { -namespace Properties { -NEW_TYPE_TAG(MyBaseTypeTag1); -NEW_TYPE_TAG(MyBaseTypeTag2); - -NEW_TYPE_TAG(MyDerivedTypeTag, INHERITS_FROM(MyBaseTypeTag1, MyBaseTypeTag2)); -}} -\end{lstlisting} - -\subsubsection{Declaring Property Tags} -New property tags, i.e. labels for properties, are declared -using -\begin{lstlisting}[style=DumuxCode] -NEW_PROP_TAG(NewPropTagName); -\end{lstlisting} -A property tag can be declared arbitrarily often, in fact it is -recommended that all properties are declared in each file where they -are used. - -\vskip1ex\noindent -Example: -\begin{lstlisting}[style=DumuxCode] -namespace Dumux { -namespace Properties { -NEW_PROP_TAG(MyPropertyTag); -}} -\end{lstlisting} - -\subsubsection{Defining Properties} -The value of a property on a given node of the type tag hierarchy is -defined using -\begin{lstlisting}[style=DumuxCode] -SET_PROP(TypeTagName, PropertyTagName) -{ - // arbitrary body of a struct -}; -\end{lstlisting} -For each program, a property itself can be declared at most once, -although properties may be overwritten for derived type tags. - -Also, the following convenience macros are available to define simple -properties: -\begin{lstlisting}[style=DumuxCode] -SET_TYPE_PROP(TypeTagName, PropertyTagName, type); -SET_BOOL_PROP(TypeTagName, PropertyTagName, booleanValue); -SET_INT_PROP(TypeTagName, PropertyTagName, integerValue); -SET_SCALAR_PROP(TypeTagName, PropertyTagName, floatingPointValue); -\end{lstlisting} - -\vskip1ex\noindent -Example: -\begin{lstlisting}[style=DumuxCode] -namespace Dumux { -namespace Properties { -NEW_TYPE_TAG(MyTypeTag); - -NEW_PROP_TAG(MyCustomProperty); -NEW_PROP_TAG(MyType); - -NEW_PROP_TAG(MyBoolValue); -NEW_PROP_TAG(MyIntValue); -NEW_PROP_TAG(MyScalarValue); - -SET_PROP(MyTypeTag, MyCustomProperty) -{ - static void print() { std::cout << "Hello, World!\n"; } -}; -SET_TYPE_PROP(MyTypeTag, MyType, unsigned int); - -SET_BOOL_PROP(MyTypeTag, MyBoolValue, true); -SET_INT_PROP(MyTypeTag, MyIntValue, 12345); -SET_SCALAR_PROP(MyTypeTag, MyScalarValue, 12345.67890); -}} -\end{lstlisting} - -\subsubsection{Un-setting Properties} -Sometimes an inherited properties do not make sense for a certain -node in the type tag hierarchy. These properties can be explicitly -un-set using -\begin{lstlisting}[style=DumuxCode] -UNSET_PROP(TypeTagName, PropertyTagName); -\end{lstlisting} -The un-set property can not be set for the same type tag, but of -course derived type tags may set it again. - -\vskip1ex\noindent -Example: -\begin{lstlisting}[style=DumuxCode] -namespace Dumux { -namespace Properties { -NEW_TYPE_TAG(BaseTypeTag); -NEW_TYPE_TAG(DerivedTypeTag, INHERITS_FROM(BaseTypeTag)); - -NEW_PROP_TAG(TestProp); - -SET_TYPE_PROP(BaseTypeTag, TestProp, int); -UNSET_PROP(DerivedTypeTag, TestProp); -// trying to access the 'TestProp' property for 'DerivedTypeTag' -// will trigger a compiler error! -}} -\end{lstlisting} - -\subsubsection{Converting Tag Names to Tag Types} -For the \Cplusplus compiler, property and type tags are like ordinary -types. Both can thus be used as template arguments. To convert a -property tag name or a type tag name into the corresponding type, the -macros \texttt{TTAG(TypeTagName)} and \texttt{PTAG(PropertyTagName)} -ought to be used. - -\subsubsection{Retrieving Property Values} -The value of a property can be retrieved using -\begin{lstlisting}[style=DumuxCode] -GET_PROP(TypeTag, PropertyTag) -\end{lstlisting} -or using the convenience macros -\begin{lstlisting}[style=DumuxCode] -GET_PROP_TYPE(TypeTag, PropertyTag) -GET_PROP_VALUE(TypeTag, PropertyTag) -\end{lstlisting} - -\vskip1ex -\noindent -The first convenience macro retrieves the type defined using -\texttt{SET\_TYPE\_PROP} and is equivalent to -\begin{lstlisting}[style=DumuxCode] -GET_PROP(TypeTag, PropertyTag)::type -\end{lstlisting} -while the second convenience macro retrieves the value of any property -defined using one of the macros \texttt{SET\_}$\{$\texttt{INT,BOOL,SCALAR}$\}$\texttt{\_PROP} and is -equivalent to -\begin{lstlisting}[style=DumuxCode] -GET_PROP(TypeTag, PropertyTag)::value -\end{lstlisting} - -\vskip1ex\noindent -Example:\nolinebreak -\begin{lstlisting}[style=DumuxCode] -template -class MyClass { - // retrieve the ::value attribute of the 'NumEq' property - enum { numEq = GET_PROP(TypeTag, NumEq)::value }; - // retrieve the ::value attribute of the 'NumPhases' property using the convenience macro - enum { numPhases = GET_PROP_VALUE(TypeTag, NumPhases) }; - - // retrieve the ::type attribute of the 'Scalar' property - typedef typename GET_PROP(TypeTag, Scalar)::type Scalar; - // retrieve the ::type attribute of the 'Vector' property using the convenience macro - typedef typename GET_PROP_TYPE(TypeTag, Vector) Vector; -}; -\end{lstlisting} - -\subsubsection{Nesting Property Definitions} -Inside property definitions there is access to all other properties -which are defined somewhere on the type tag hierarchy. The node for -which the current property is requested is available via the keyword -\texttt{TypeTag}. Inside property class bodies this can be used to -retrieve other properties using the \texttt{GET\_PROP} macros. - -\vskip1ex\noindent -Example: -\begin{lstlisting}[style=DumuxCode] -SET_PROP(MyModelTypeTag, Vector) -{ -private: typedef typename GET_PROP_TYPE(TypeTag, Scalar) Scalar; -public: typedef std::vector type; -}; -\end{lstlisting} - -\subsection{A Self-Contained Example} -As a concrete example, let us consider some kinds of cars: Compact -cars, sedans, trucks, pickups, military tanks and the Hummer-H1 sports -utility vehicle. Since all these cars share some characteristics, it -makes sense to inherit those from the closest matching car type and -only specify the properties which are different. Thus, an inheritance -diagram for the car types above might look like outlined in Figure -\ref{fig:car-hierarchy}. - -\begin{figure}[t] - \centering - \subfloat[]{ - \begin{tikzpicture} - [cars/.style={rectangle,draw=black,rounded corners,minimum width=2.5cm,node distance=0.5cm}] - % place nodes - \node[cars] (compact) {Compact car}; - \node[cars] (sedan) [below=of compact] {Sedan}; - \node[cars] (truck) [right=of compact] {Truck}; - \node[cars] (pickup) [below right= of sedan] {Pickup}; - \node[cars] (tank) [right=of truck] {Tank}; - \node[cars] (hummer) [below right= of pickup] {Hummer}; - % add edges - \draw [-latex',thick] (compact) -- (sedan); - \draw [-latex',thick] (sedan) -- (pickup); - \draw [-latex',thick] (truck) -- (pickup); - \draw [-latex',thick] (tank) -- (hummer); - \draw [-latex',thick] (pickup) -- (hummer); - \end{tikzpicture} - \label{fig:car-hierarchy} - } - \hspace*{0.5cm} - \subfloat[]{ - \begin{tikzpicture} - [propertyBox/.style={rectangle,draw=black,minimum width=4.5cm,node distance=0.1cm}] - \node[propertyBox] (gasUsage) {GasUsage}; - \node[propertyBox] (speed) [below=of gasUsage] {TopSpeed}; - \node[propertyBox] (seats) [below=of speed] {NumSeats}; - \node[propertyBox] (automatic) [below=of seats] {AutomaticTransmission}; - \node[propertyBox] (calibre) [below=of automatic] {CannonCalibre}; - \node[propertyBox] (payload) [below=of calibre] {Payload}; - \end{tikzpicture} - \label{fig:car-propertynames} - } - \caption{\textbf{(a)}~A possible property inheritance graph for - various kinds of cars. The lower nodes inherit from higher ones; - Inherited properties from nodes on the right take precedence over the - properties defined on the left. \textbf{(b)}~Property names - which make sense for at least one of the car types of (a).} -\end{figure} - -Using the \Dumux property system, this inheritance hierarchy is -defined by: -\begin{lstlisting}[name=propsyscars,style=DumuxCode] -#include -#include - -namespace Dumux { -namespace Properties { -NEW_TYPE_TAG(CompactCar); -NEW_TYPE_TAG(Truck); -NEW_TYPE_TAG(Tank); -NEW_TYPE_TAG(Sedan, INHERITS_FROM(CompactCar)); -NEW_TYPE_TAG(Pickup, INHERITS_FROM(Sedan, Truck)); -NEW_TYPE_TAG(HummerH1, INHERITS_FROM(Pickup, Tank)); -\end{lstlisting} - -Figure \ref{fig:car-propertynames} lists a few property names which -make sense for at least one of the nodes of Figure -\ref{fig:car-hierarchy}. These property names can be declared as -follows: -\begin{lstlisting}[name=propsyscars,style=DumuxCode] -NEW_PROP_TAG(TopSpeed); // [km/h] -NEW_PROP_TAG(NumSeats); // [] -NEW_PROP_TAG(CanonCaliber); // [mm] -NEW_PROP_TAG(GasUsage); // [l/100km] -NEW_PROP_TAG(AutomaticTransmission); // true/false -NEW_PROP_TAG(Payload); // [t] -\end{lstlisting} - -\noindent -So far, the inheritance hierarchy and the property names are completely -separate. What is missing is setting some values for the property -names on specific nodes of the inheritance hierarchy. Let us assume -the following: -\begin{itemize} -\item For a compact car, the top speed is the gas usage in $\unitfrac{l}{100km}$ - times $30$, the number of seats is $5$ and the gas usage is - $\unitfrac[4]{l}{100km}$. -\item A truck is by law limited to $\unitfrac[100]{km}{h}$ top speed, the number - of seats is $2$, it uses $\unitfrac[18]{l}{100km}$ and has a cargo payload of - $\unit[35]{t}$. -\item A tank exhibits a top speed of $\unitfrac[60]{km}{h}$, uses $\unitfrac[65]{l}{100km}$ - and features a $\unit[120]{mm}$ diameter canon -\item A sedan has a gas usage of $\unitfrac[7]{l}{100km}$, as well as an automatic - transmission, in every other aspect it is like a compact car. -\item A pick-up truck has a top speed of $\unitfrac[120]{km}{h}$ and a payload of - $\unit[5]{t}$. In every other aspect it is like a sedan or a truck but if in - doubt, it is more like a truck. -\item The Hummer-H1 SUV exhibits the same top speed as a pick-up - truck. In all other aspects it is similar to a pickup and a tank, - but, if in doubt, more like a tank. -\end{itemize} - -\noindent -Using the \Dumux property system, these assumptions are formulated -using -\begin{lstlisting}[name=propsyscars,style=DumuxCode] -SET_INT_PROP(CompactCar, TopSpeed, GET_PROP_VALUE(TypeTag, GasUsage) * 30); -SET_INT_PROP(CompactCar, NumSeats, 5); -SET_INT_PROP(CompactCar, GasUsage, 4); - -SET_INT_PROP(Truck, TopSpeed, 100); -SET_INT_PROP(Truck, NumSeats, 2); -SET_INT_PROP(Truck, GasUsage, 18); -SET_INT_PROP(Truck, Payload, 35); - -SET_INT_PROP(Tank, TopSpeed, 60); -SET_INT_PROP(Tank, GasUsage, 65); -SET_INT_PROP(Tank, CanonCaliber, 120); - -SET_INT_PROP(Sedan, GasUsage, 7); -SET_BOOL_PROP(Sedan, AutomaticTransmission, true); - -SET_INT_PROP(Pickup, TopSpeed, 120); -SET_INT_PROP(Pickup, Payload, 5); - -SET_INT_PROP(HummerH1, TopSpeed, GET_PROP_VALUE(TTAG(Pickup), TopSpeed)); -\end{lstlisting} - -\noindent -At this point, the Hummer-H1 has a $\unit[120]{mm}$ canon which it inherited -from its military ancestor. It can be removed by -\begin{lstlisting}[name=propsyscars,style=DumuxCode] -UNSET_PROP(HummerH1, CanonCaliber); - -}} // close namespaces -\end{lstlisting} - -\noindent -Now property values can be retrieved and some diagnostic messages can -be generated. For example -\begin{lstlisting}[name=propsyscars,style=DumuxCode] -int main() -{ - std::cout << "top speed of sedan: " << GET_PROP_VALUE(TTAG(Sedan), TopSpeed) << "\n"; - std::cout << "top speed of truck: " << GET_PROP_VALUE(TTAG(Truck), TopSpeed) << "\n"; - - std::cout << PROP_DIAGNOSTIC(TTAG(Sedan), TopSpeed); - std::cout << PROP_DIAGNOSTIC(TTAG(HummerH1), CanonCaliber); - - Dumux::Properties::print(); -} -\end{lstlisting} -will yield the following output: -\begin{lstlisting}[style=Bash, basicstyle=\ttfamily\scriptsize\let\textcolor\textcolordummy] -$ top speed of sedan: 210 -$ top speed of truck: 100 -$ Properties for Sedan: -$ bool AutomaticTransmission = 'true' defined at test_propertysystem.cc:68 -$ int GasUsage = '7' defined at test_propertysystem.cc:67 -$ Inherited from CompactCar: -$ int NumSeats = '5' defined at test_propertysystem.cc:55 -$ int TopSpeed = '::Dumux::Properties::GetProperty::p::value * 30' defined at test_propertysystem.cc:54 -\end{lstlisting} - -\subsection{Property Values} -To get the value of a property use: -\begin{description} -\item[\texttt{{\small GET\_PROP\_VALUE:}}] -Always returns the \emph{compile-time} specified value of the property. -\end{description} diff --git a/doc/handbook/5_restartsimulations.tex b/doc/handbook/5_restartsimulations.tex new file mode 100644 index 0000000000000000000000000000000000000000..80b769da4288a2db0989cc32e9d613b160a02938 --- /dev/null +++ b/doc/handbook/5_restartsimulations.tex @@ -0,0 +1,19 @@ +\section{Restart \Dumux Simulations} +\label{sc_restartsimulations} + +\Dumux has some experimental support for check-pointing (restarting paused/stopped/crashed simulations). +You can restart a \Dumux simulation from any time point where a VTK file was written out. +This is currently only supported for sequential, non-adaptive simulations. For adaptive simulation +the full hierarchical grid has to be stored. This is usually done with the grid's \texttt{BackupRestoreFacility}. +There is currently no special support by \Dumux for that, but it is possible to implement +a restart using \texttt{BackupRestoreFacility} with plain Dune. + +For VTK files the output can be read with the free function \texttt{loadSolution}. Grids can be read with +the \texttt{Dumux::VTKReader} or you can simply recreate the grid as you did in the first simulation run. + +Unfortunately, writing double-precision floating point numbers to VTK files is only available with Dune master (will be in 2.7). +That's why we currently only support single precision restart, meaning some information will be lost if you are computing +in double precision. + +The restart capabilities will hopefully be improved in future versions of \Dumux-3. +We are happy about any contributions (especially HDF5 / XDMF support, improvement of VTK support). diff --git a/doc/handbook/5_spatialdiscretizations.tex b/doc/handbook/5_spatialdiscretizations.tex deleted file mode 100644 index b8861d74797093ba2faaf8ffce509b705c9c8936..0000000000000000000000000000000000000000 --- a/doc/handbook/5_spatialdiscretizations.tex +++ /dev/null @@ -1,212 +0,0 @@ -\section{Spatial Discretization Schemes} -\label{spatialdiscretization} - -We discretize space with the cell-centered finite volume method (\ref{box} ), the box method (\ref{cc}) -or a staggered grid scheme. -Grid adaption is available for both box and cell-centered finite volume method. -Note that the current implementation only ensures mass conservation for incompressible fluids. -In general, the spatial parameters, especially the porosity, have to be assigned on -the coarsest level of discretization. - -\subsection{Box Method -- A Short Introduction}\label{box} - -The so called box method unites the advantages of the finite-volume (FV) and -finite-element (FE) methods. - -First, the model domain $G$ is discretized with a FE mesh consisting of nodes -$i$ and corresponding elements $E_k$. Then, a secondary FV mesh is constructed -by connecting the midpoints and barycenters of the elements surrounding node -$i$ creating a box $B_i$ around node $i$ (see Figure \ref{pc:box}a). - -\begin{figure} [ht] -\includegraphics[width=0.8\linewidth,keepaspectratio]{PNG/box_disc.png} -\caption{\label{pc:box} Discretization of the box method} -\end{figure} - -The FE mesh divides the box $B_i$ into subcontrolvolumes (scv's) $b^k_i$ -(see Figure \ref{pc:box}b). Figure \ref{pc:box}c shows the finite element $E_k$ -and the scv's $b^k_i$ inside $E_k$, which belong to four different boxes $B_i$. -Also necessary for the discretization are the faces of the subcontrolvolumes (scvf's) -$e^k_{ij}$ between the scv's $b^k_i$ and $b^k_j$, where $|e^k_{ij}|$ is the length -of the scvf. The integration points $x^k_{ij}$ on $e^k_{ij}$ and the outer normal -vector $\mathbf n^k_{ij}$ are also to be defined (see Figure \ref{pc:box}c). - -The advantage of the FE method is that unstructured grids can be used, while the -FV method is mass conservative. The idea is to apply the FV method (balance of -fluxes across the interfaces) to each FV box $B_i$ and to get the fluxes across -the interfaces $e^k_{ij}$ at the integration points $x^k_{ij}$ from the FE approach. -Consequently, at each scvf the following expression results: - -\begin{equation} - f(\tilde u(x^k_{ij})) \cdot \mathbf n^k_{ij} \: |e^k_{ij}| \qquad \textrm{with} - \qquad \tilde u(x^k_{ij}) = \sum_i N_i(x^k_{ij}) \cdot \hat u_i . -\end{equation} - -In the following, the discretization of the balance equation is going to be derived. -From the \textsc{Reynolds} transport theorem follows the general balance equation: - -\begin{equation} - \underbrace{\int_G \frac{\partial}{\partial t} \: u \: dG}_{1} - + \underbrace{\int_{\partial G} (\mathbf{v} u + \mathbf w) \cdot \textbf n \: d\varGamma}_{2} = \underbrace{\int_G q \: dG}_{3} -\end{equation} - -\begin{equation} - f(u) = \int_G \frac{\partial u}{\partial t} \: dG + \int_{G} \nabla \cdot - \underbrace{\left[ \mathbf{v} u + \mathbf w(u)\right] }_{F(u)} \: dG - \int_G q \: dG = 0 -\end{equation} -where term 1 describes the changes of entity $u$ within a control volume over -time, term 2 the advective, diffusive and dispersive fluxes over the interfaces -of the control volume and term 3 is the source and sink term. $G$ denotes the -model domain and $F(u) = F(\mathbf v, p) = F(\mathbf v(x,t), p(x,t))$. - -Like the FE method, the box method follows the principle of weighted residuals. -In the function $f(u)$ the unknown $u$ is approximated by discrete values at the -nodes of the FE mesh $\hat u_i$ and linear basis functions $N_i$ yielding an -approximate function $f(\tilde u)$. For $u\in \lbrace \mathbf v, p, x^\kappa \rbrace$ -this means: - -\begin{minipage}[b]{0.47\textwidth} -\begin{equation} -\label{eq:p} - \tilde p = \sum_i N_i \hat{p_i} -\end{equation} -\begin{equation} -\label{eq:v} - \tilde{\mathbf v} = \sum_i N_i \hat{\mathbf v} -\end{equation} -\begin{equation} -\label{eq:x} - \tilde x^\kappa = \sum_i N_i \hat x^\kappa -\end{equation} -\end{minipage} -\hfill -\begin{minipage}[b]{0.47\textwidth} -\begin{equation} -\label{eq:dp} - \nabla \tilde p = \sum_i \nabla N_i \hat{p_i} -\end{equation} -\begin{equation} -\label{eq:dv} - \nabla \tilde{\mathbf v} = \sum_i \nabla N_i \hat{\mathbf v} -\end{equation} -\begin{equation} -\label{eq:dx} - \nabla \tilde x^\kappa = \sum_i \nabla N_i \hat x^\kappa . -\end{equation} -\end{minipage} - -Due to the approximation with node values and basis functions the differential -equations are not exactly fulfilled anymore but a residual $\varepsilon$ is produced. - -\begin{equation} - f(u) = 0 \qquad \Rightarrow \qquad f(\tilde u) = \varepsilon -\end{equation} - -Application of the principle of weighted residuals, meaning the multiplication -of the residual $\varepsilon$ with a weighting function $W_j$ and claiming that -this product has to vanish within the whole domain, - -\begin{equation} - \int_G W_j \cdot \varepsilon \: \overset {!}{=} \: 0 \qquad \textrm{with} \qquad \sum_j W_j =1 -\end{equation} -yields the following equation: - -\begin{equation} - \int_G W_j \frac{\partial \tilde u}{\partial t} \: dG + \int_G W_j - \cdot \left[ \nabla \cdot F(\tilde u) \right] \: dG - \int_G W_j - \cdot q \: dG = \int_G W_j \cdot \varepsilon \: dG \: \overset {!}{=} \: 0 . -\end{equation} - -Then, the chain rule and the \textsc{Green-Gaussian} integral theorem are applied. - -\begin{equation} - \int_G W_j \frac{\partial \sum_i N_i \hat u_i}{\partial t} \: dG - + \int_{\partial G} \left[ W_j \cdot F(\tilde u)\right] - \cdot \mathbf n \: d\varGamma_G + \int_G \nabla W_j \cdot F(\tilde u) - \: dG - \int_G W_j \cdot q \: dG = 0 -\end{equation} - -A mass lumping technique is applied by assuming that the storage capacity is -reduced to the nodes. This means that the integrals $M_{i,j} = \int_G W_j \: N_i \: dG$ -are replaced by the mass lumping term $M^{lump}_{i,j}$ which is defined as: - -\begin{equation} - M^{lump}_{i,j} =\begin{cases} \int_G W_j \: dG = \int_G N_i \: dG = V_i &i = j\\ - 0 &i \neq j\\ - \end{cases} -\end{equation} -where $V_i$ is the volume of the FV box $B_i$ associated with node $i$. -The application of this assumption in combination with -$\int_G W_j \:q \: dG = V_i \: q$ yields - -\begin{equation} - V_i \frac{\partial \hat u_i}{\partial t} - + \int_{\partial G} \left[ W_j \cdot F(\tilde u)\right] - \cdot \mathbf n \: d\varGamma_G + \int_G \nabla W_j \cdot F(\tilde u) - \: dG- V_i \cdot q = 0 \, . -\end{equation} - -Defining the weighting function $W_j$ to be piecewisely constant over a -control volume box $B_i$ - -\begin{equation} - W_j(x) = \begin{cases} - 1 &x \in B_i \\ - 0 &x \notin B_i\\ - \end{cases} -\end{equation} - -causes $\nabla W_j = 0$: - -\begin{equation} -\label{eq:disc1} - V_i \frac{\partial \hat u_i}{\partial t} - + \int_{\partial B_i} \left[ W_j \cdot F(\tilde u)\right] - \cdot \mathbf n \; d{\varGamma}_{B_i} - V_i \cdot q = 0 . -\end{equation} - -The consideration of the time discretization and inserting $W_j = 1$ finally -leads to the discretized form which will be applied to the mathematical -flow and transport equations: - -\begin{equation} -\label{eq:discfin} - V_i \frac{\hat u_i^{n+1} - \hat u_i^{n}}{\Delta t} - + \int_{\partial B_i} F(\tilde u^{n+1}) \cdot \mathbf n - \; d{\varGamma}_{B_i} - V_i \: q^{n+1} \: = 0 -\end{equation} - -\subsection{Cell Centered Finite Volume Method -- A Short Introduction}\label{cc} - -\begin{figure} [ht] -\centering -\includegraphics[width=0.4\linewidth,keepaspectratio]{PNG/cc_disc.png} -\caption{\label{pc:cc} Discretization of the cell centered finite volume method} -\end{figure} - -The cell centered finite volume method uses the elements of the grid as control volumes. -For each control volume all discrete values are determined at the element/control -volume center (see Figure~\ref{pc:cc}). -The mass or energy fluxes are evaluated at the integration points ($x_{ij}$), -which are located at the midpoints of the control -volume faces. This is a two point flux approximation since the flux between -the element/control volume centers $i$ and $j$ is calculated -only with information from these two points. In contrast the box method uses -a multi-point flux approximation where all nodes of the -element influence the flux between two specific nodes. \\ -Neumann boundary conditions are applied at the boundary control volume faces -and Dirichlet boundary conditions at the boundary control volumes. \\ -The cell centered finite volume method is robust and mass conservative but -should only be applied for structured grids -(the control volume face normal vector ($n_{ij}$) should be parallel to the -direction of the gradient between the two element/control -volume centers). - -% \subsubsection{MPFA}\label{staggered} -% TODO -% \subsubsection{NLTPFA}\label{staggered} -% TODO - -% \subsection{Staggered Grid -- A Short Introduction}\label{staggered} -% TODO - diff --git a/doc/handbook/5_stepsofasimulation.tex b/doc/handbook/5_stepsofasimulation.tex deleted file mode 100644 index d95e350aa94cf004be9bd1118f06f733baae9b24..0000000000000000000000000000000000000000 --- a/doc/handbook/5_stepsofasimulation.tex +++ /dev/null @@ -1,412 +0,0 @@ -\section{Steps of a \Dumux Simulation} -\label{flow} - - -This chapter is supposed to show how things are ``handed around'' in \Dumux. It -is not a comprehenisve guide through the modeling framework of \Dumux, but -hopefully it will help getting to grips with it. - -In Section \ref{content} the structure of \Dumux is shown from a \emph{content} -point of view. -% TODO: revise section about implementation structure -% Section \ref{implementation} however is written from the point of view of the \emph{implementation}. -% The same coloration in the flowcharts of both sections refers to the same level of calculation. For keeping things -% simple, the program flow of a \verb+2p+ model is shown in section \ref{implementation}. There are extensive comments -% regarding the formating in the tex file: so feel free, to enhance this description. - -\subsection{Structure -- by Content} - -\label{content} -In Figure \ref{fig:algorithm}, the algorithmic representations of a monolithical -solution solution scheme is illustrated down to the element level. - -\begin{figure}[hbt] -% \begin{tabular}{ l | l } -% \begin{minipage}[t]{0.48\textwidth} -\setcounter{thingCounter}{0} - -\scriptsize -\sffamily -\begin{tabbing} -\textbf{{\begin{turn}{45}\color{black}\numberThis{main}{init}\end{turn}}} \= -\textbf{{\begin{turn}{45}\color{dumuxBlue}\numberThis{time step}{prep}\end{turn}}} \= -\textbf{{\begin{turn}{45}\color{Mulberry}\numberThis{\textsc{Newton}}{elem}\end{turn}}} \= -\textbf{{\begin{turn}{45}\color{dumuxYellow}\numberThis{element}{calc}\end{turn}}} \= \\ -\\ -\color{black}initialize \\ -\color{black}\textbf{foreach} time step\\ - - \> \color{dumuxBlue}prepare update\\ - \> \color{dumuxBlue}\textbf{foreach} \textsc{Newton} iteration \\ - - \> \> \color{Mulberry}\textbf{foreach} element \\ - - \> \> \> \color{dumuxYellow}- calculate element \\ - \> \> \> \color{dumuxYellow}\; residual vector and \\ - \> \> \> \color{dumuxYellow}\; Jacobian matrix\\ - \> \> \> \color{dumuxYellow}- assemble into global\\ - \> \> \> \color{dumuxYellow}\; residual vector and \\ - \> \> \> \color{dumuxYellow}\;{Jacobian} matrix \\ - - \> \> \color{Mulberry}\textbf{endfor} \\ - - \> \> \color{Mulberry}solve linear system\\ - \> \> \color{Mulberry}update solution\\ - \> \> \color{Mulberry}check for \textsc{Newton} convergence\\ - \> \color{dumuxBlue}\textbf{endfor}\\ - \> \color{dumuxBlue}- adapt time step size, \\ - \> \color{dumuxBlue}\; possibly redo with smaller step size\\ - \> \color{dumuxBlue}- write result\\ -\color{black}\textbf{endfor}\\ -\color{black}finalize -\end{tabbing} - -% \end{minipage} -% -% & - -% TODO: revise second figure -% \begin{minipage}[t]{0.48\textwidth} -% \setcounter{thingCounter}{0} -% -% \scriptsize -% \sffamily -% \begin{tabbing} -% \textbf{{\begin{turn}{45}\color{black}1. main\end{turn}}} \= -% \textbf{{\begin{turn}{45}\color{dumuxBlue}2. time step\end{turn}}} \= -% \textbf{{\begin{turn}{45}\color{Mulberry}3. \textsc{IMPES/C}\end{turn}}} \= -% \textbf{{\begin{turn}{45}\color{dumuxYellow}4. element\end{turn}}} \= \\ -% \\ -% \color{black}initialize \\ -% \color{black}\textbf{foreach} time step\\ -% -% \> \color{dumuxBlue}prepare update\\ -% \> \color{dumuxBlue}\textbf{foreach} \textsc{IMPES/C} step \\ -% \> \> \color{Mulberry}\textbf{if} grid is adaptive\\ -% \> \> \> \color{dumuxYellow}- calculate refinement indicator\\ -% \> \> \> \color{dumuxYellow}- mark elements, adapt the grid\\ -% \> \> \> \color{dumuxYellow}- map old solution to new grid\\ -% \> \> \color{Mulberry}- calculate {flow field}\\ -% \> \> \color{Mulberry}\textbf{foreach} element \\ -% -% \> \> \> \color{dumuxYellow}- calculate element stiffness matrix \\ -% \> \> \> \color{dumuxYellow}- assemble into global matrix \\ -% -% \> \> \color{Mulberry} \textbf{endfor} \\ -% \> \> \color{Mulberry} solve linear system\\ -% -% \> \> \color{Mulberry}- calculate {transport} \\ -% \> \> \color{Mulberry}\; (saturations, concentrations,...) \\ -% \> \> \color{Mulberry}\textbf{foreach} element \\ -% \> \> \> \color{dumuxYellow}-calculate update (explicitly) \\ -% \> \> \> \color{dumuxYellow}- adapt time step ({CFL}-like criterion) \\ -% \> \> \color{Mulberry}\textbf{endfor} \\ -% \> \> \color{Mulberry}- update old solution \\ -% \> \> \color{Mulberry}- postprocess (flash calculation, etc.)\\ -% \> \color{dumuxBlue}\textbf{endfor}\\ -% \> \color{dumuxBlue}- write result\\ -% \color{black}\textbf{endfor}\\ -% finalize -% \end{tabbing} -% -% \end{minipage} -% \end{tabular} - -% \caption{Structure of a fully implicit (\textbf{left}) and a sequential -% (\textbf{right}) scheme in \Dumux.} -\caption{Structure of a monolithical solution scheme in \Dumux.} -\label{fig:algorithm} -\end{figure} - -% \subsection{Structure -- by Implementation} -% \label{implementation} -% This section is supposed to help you in getting an idea how things are handled in -% \Dumux and in which files things are written down. -% This is not intuitivly clear, therefore it is mentioned for each \fbox{step-stone}. -% \textbf{called by} tells you from which file a function is -% accessed. \textbf{implemented in} tells you in which file the function is written -% down. The name of the function is set in \verb+typewriter+. -% Being a function is indicated by round brackets \verb+()+ but only the function -% name is given and not the full signature (arguments...) . -% Comments regarding the events within one step-stone are set \scriptsize{smaller}. -% -% \begin{landscape} -% \pagestyle{empty} % switch off headings and footer in order to get more space for the flowchart -% \setlength{\voffset}{4.2cm} -% -% % command for blocks -% \newcommand{\step}[6]{ -% \begin{minipage}{7.5cm} -% {\tiny \color{#1}\texttt{#2} $\Rightarrow$ \texttt{#3}}\\ -% \fcolorbox{#1}{white}{ -% \begin{minipage}{7.0cm} -% \begin{scriptsize} -% \texttt{#4} \hfill \color{gray}in: #5\color{black}\\ -% \hphantom{m}\begin{minipage}[t]{6.8cm}#6\end{minipage} -% \end{scriptsize} -% \end{minipage}} -% \end{minipage} -% } -% -% % command for the arrow with text -% \newcommand{\longArrow}[1]{ -% \begin{minipage}[b]{7.5cm} -% \fcolorbox{white}{white}{ -% \begin{minipage}[b]{7.0cm} -% \begin{center} -% \begin{scriptsize} -% $\overrightarrow{ %an arrow under which things may be written -% \begin{array}{c} % in order to be able to write multiple lines under the arrow -% #1\\ -% \hphantom{\hspace{6.5cm}} -% \end{array} -% }$ -% \end{scriptsize} -% \end{center} -% \end{minipage}% -% } -% \end{minipage}% -% \hphantom{ $\overrightarrow{}$}% -% } -% -% % command for the arrow between steps -% \newcommand{\shortArrow}{$\overrightarrow{}$} -% -% % command for marking things as model specific -% \newcommand{\modelSpecific}{\emph{model specific}\xspace} -% -% % the distance between two lines -% \newcommand{\dummyDistance}{\\[4\baselineskip]} -% -% % THE FLOW CHART STARTS HERE -% \noindent -% \step{black}{main()}{Dumux::start() $\Rightarrow$ start\_()}{start\_()}{start.hh}% -% {start the simulation} -% \shortArrow -% \step{black}{start\_()}{timeManager.init()}{init()}{timemanager.hh}% -% {initialization} -% \shortArrow -% \step{black}{start\_()}{timeManager.run()}{run()}{timemanager.hh}% -% {time step management} -% \dummyDistance -% % -% \longArrow{ -% \textnormal{\texttt{while(!finished)}}\\ -% \textnormal{\color{black}main} -% \rightarrow \textnormal{\color{dumuxBlue}time step} -% } -% \step{dumuxBlue}{run()}{problem->timeIntegration()}{timeIntegration()}{implicitproblem.hh}% -% {execute time integration scheme}% -% \longArrow{ -% \textnormal{define number of allowed \textsc{Newton} fails}\\ -% \textnormal{(each halving dt)} -% } -% \dummyDistance -% % -% \step{dumuxBlue}{timeIntegration()}{model->update()}{update()}{implicitmodel.hh}% -% {sth like numerical model} -% \shortArrow -% \step{dumuxBlue}{update()}{solver.execute()}{execute()}{newtonmethod.hh}% -% {applying \textsc{Newton} method\\ -% keeps track of things, catching errors} -% \longArrow{ -% \textnormal{\color{dumuxBlue}time step} -% \rightarrow \textnormal{\color{Mulberry}Newton step}\\ -% \texttt{while(ctl.newtonProceed()}\\ -% \textnormal{uLastIter = uCurrentIter(model.uCur())} -% } -% \dummyDistance -% % -% \noindent -% \step{Mulberry}{execute() $\Rightarrow$ execute\_()}{jacobianAsm.assemble()}{assemble()}{implicitassembler.hh}% -% {linearize the problem:\\ -% add all element contributions to global \textsc{Jacobian} -% and global residual}% -% \shortArrow -% \step{Mulberry}{assemble() $\Rightarrow$ asImp\_().assemble\_()}{resetSystem\_()}{resetSystem\_()}{implicitassembler.hh}% -% {set r.h.s. (i.e. residual)\\ -% set \textsc{Jacobian} to zero } -% \longArrow{ -% \textnormal{\color{Mulberry}Newton step} -% \rightarrow \textnormal{\color{dumuxYellow}element}\\ -% \texttt{loop all elements}\\ -% } -% \dummyDistance -% % -% \noindent -% \step{dumuxYellow}{assemble() $\Rightarrow$ asImp\_().assemble\_()}{asImp\_().assembleElement\_()}{assembleElement\_()}{e.g. boxassembler.hh}% -% {call local \textsc{Jacobian} and residual assembly}% -% \shortArrow -% \step{dumuxYellow}{assembleElement\_()}{model\_().localJacobian().assemble()}{assemble()}{implicitlocaljacobian.hh}% -% {set curr. element, update element's fin.vol.geom.\\ -% reset local \textsc{Jacobian} to 0\\ -% update types of boundaries on this element}% -% \shortArrow -% \step{dumuxYellow}{assemble()}{prevVolVars\_.update(),curVolVars\_.update()}{update()}{e.g. 2pvolumevariables.hh}% -% {call model (e.g. \texttt{2p})specific update of quantities defined for the volume:\\ -% variables for the \emph{current} and \emph{previous} timestep}% -% \dummyDistance -% % -% \noindent -% \step{dumuxYellow}{update()}{completeFluidState()}{completeFluidState()}{e.g. 2pvolumevariables.hh}% -% {calculate all required fluid properties from the primary variables, -% here the fluid system does the real work:\\ -% calculates, saves, and provides: densities, etc.} -% \shortArrow -% \step{dumuxYellow}{assemble()}{localResidual().eval()$\Rightarrow$asImp\_().eval()}{eval()}{e.g. implicitlocalresidual.hh}% -% {the element's local residual is calculated:\\ -% see the next two stepstones}% -% \shortArrow -% \step{dumuxYellow}{eval()}{asImp\_().evalFluxes\_()}{evalFluxes\_()}{e.g. boxlocalresidual.hh}% -% {evaluate the fluxes going into each finite volume, -% this is \modelSpecific} -% \dummyDistance -% % -% \step{dumuxYellow}{evalFluxes\_()}{this$\rightarrow$asImp\_().computeFlux()}{computeFlux()}{e.g. 2plocalresidual.hh}% -% {this calculate the \modelSpecific fluxes (e.g. advective and diffusive) -% using the \texttt{FluxVariables}} -% \shortArrow -% \step{dumuxYellow}{eval()}{asImp\_().evalVolumeTerms\_()}{evalVolumeTerms\_()}{implicitlocalresidual.hh}% -% {evaluate the \modelSpecific storage and source terms for each finite volume}% -% \shortArrow -% \step{dumuxYellow}{eval()}{asImp\_().evalBoundary\_()}{evalBoundary\_()}{implicitlocalresidual.hh}% -% {evaluate the \modelSpecific boundary conditions}% -% \dummyDistance -% % -% \step{dumuxYellow}{assemble()}{asImp\_().evalPartialDerivative\_()}{evalPartialDerivative\_()}{e.g. implicitlocaljacobian.hh}% -% {actually calculate the element's (local) \textsc{Jacobian}\\ -% matrix a property chooses backward/central/foward\\ -% differences. here: central differences} -% \shortArrow -% \begin{minipage}{0.50\textwidth} -% \begin{scriptsize}\textnormal{approximation of partial derivatives: numerical differentiation}\end{scriptsize}\\ -% \begin{scriptsize}\textnormal{add $\pm \epsilon$ solution, divide difference of residual by $2\epsilon$}\end{scriptsize}\\ -% \begin{scriptsize}\textnormal{all partial derivatives for the element from the local \textsc{Jacobian} matrix}\end{scriptsize}\\ -% $\left \lbrace -% \begin{tabular}{l}%these question marks are for the \verb, not meant as ``unclear'' -% \verb?priVars[pvIdx]+=eps?\\ -% \begin{scriptsize}\textnormal{this is adding eps to the current solution}\end{scriptsize}\\ -% \verb?curVolVars_[scvIdx].update(+eps)?\\ -% \begin{scriptsize}\textnormal{recalculate volume variables, having $\epsilon$ added}\end{scriptsize}\\ -% \verb?localResidual().eval(+eps)?\\ -% \begin{scriptsize}\textnormal{calculate local residual for modified solution as before: involves}\end{scriptsize}\\ -% {\scriptsize $\begin{array}{l} -% \textnormal{- \textbf{computeFlux}}\\ -% \textnormal{- \textbf{computeStorage}}\\ -% \textnormal{- \textbf{computeSource}} \\ -% \end{array}$} \\ -% \verb?store the residual()?\\ -% \verb?repeat for priVars[pvIdx]-=eps?\\ -% \verb?derivative is (residual(+eps) - residual(-eps))/2eps?\\ -% \end{tabular} -% \right . -% $ -% \end{minipage} -% \dummyDistance -% % -% \step{dumuxYellow}{assemble\_()}{asImp\_().assembleElement\_()}{assembleElement\_()}{implicitassembler.hh}% -% {Residual of the current solution is now\\ -% ``numerically differentiated'', for the element i.e.\\ -% the local \textsc{Jacobian} matrix is calculated. }% -% \longArrow{ -% \textnormal{The contribution of a single element is done.}\\ -% \textnormal{Now, it needs to be added to the global quantities:}\\ -% \textnormal{Add to global residual and global \textsc{Jacobian}}.} -% \step{dumuxYellow}{assemble\_()}{asImp\_().assembleElement\_()}{assembleElement\_()}{e.g. boxassembler.hh} -% {Add to global residual.:\\ -% \texttt{resdidual\_[globI+=\\model\_().globalJacobian().resdidual(i)]}} -% \dummyDistance -% % -% \longArrow{ -% \textnormal{loop vertices}\\ -% \textnormal{of an element} -% } -% \step{dumuxYellow}{assemble\_()}{asImp\_().assembleElement\_()}{assembleElement\_()}{e.g. boxassembler.hh} -% {Add to global residual:\\ -% \texttt{(*matrix\_)[globI][globJ] +=\\model\_().localJacobian().mat(i,j)}} -% \longArrow{ -% \textbf{\textbf{\color{dumuxYellow}element}} -% \rightarrow \textbf{\color{Mulberry}Newton step}\\ -% \textnormal{Assembling of elements to global quantities is done.} -% } -% \dummyDistance -% % -% \step{Mulberry}{execute\_()}{while(ctl.newtonProceed())}{newtonProceed()}{newtoncontroller.hh}% -% {Print information.\\ -% Start/ stop timer.}% -% -% \longArrow{ -% \textnormal{set delta Vector to zero} \\ -% \textnormal{(this is what is}\\ -% \textnormal{solved for later)}\\ -% } -% \step{Mulberry}{execute\_()}{ctl.newtonSolveLinear()}{newtonSolveLinear()}{newtoncontroller.hh}% -% {Catching errors.\\ -% Ask the linear solver to solve the system.\\ -% i.e.: give \textsc{Jacobian}(matrix), delta(x), r.h.s.(residual) to linear solver\\ -% $\nabla r(x^k) \cdot \Delta x^k = r(x^k)$\\ -% tricky: each \textsc{Newton} step solves a linear system of equations.}% -% \shortArrow -% \step{Mulberry}{newtonSolveLinear()}{int converged = linearSolver\_.solve()}{solve()}{boxlinearsolver.hh}% -% {Solve the linear system with the chosen backend.}% -% \dummyDistance -% % -% \step{Mulberry}{execute\_()}{ctl.newtonUpdate()}{newtonUpdate()}{newtoncontroller.hh}% -% {We solved for the change in solution, but need the solution:\\ -% Calculate current (this iteration) solution\\ -% \quad from last (iteration) solution and current (iteration) change in solution:\\ -% $x^{k+1} = x^k - \Delta x^k$ where $\Delta x^k = (\nabla r(x^k))^{-1} \cdot r(x^k)$} -% \shortArrow -% \step{Mulberry}{execute\_()}{ctl.newtonEndStep()}{newtonEndStep()}{newtoncontroller.hh}% -% {Increase counter for number of \textsc{Newton} steps.\\ -% Print info.}% -% \longArrow{ -% \textnormal{check whether to do another \textsc{Newton} iteration:} \\ -% \textnormal{that is: check if the error is below tolerance or}\\ -% \textnormal{maximum number of iterations was reached.} -% } -% \dummyDistance -% % -% \longArrow{ -% \textbf{\textbf{\color{Mulberry}Newton step}} -% \rightarrow \textbf{\color{dumuxBlue}Time step}\\ -% \textnormal{\textsc{Newton} done}\\ -% \textnormal{if failed $\rightsquigarrow$ halve timestep size, restart loop}\\ -% } -% \step{dumuxBlue}{execute\_()}{ctl.newtonEnd()}{newtonEnd()}{newtoncontroller.hh}% -% {Tell the controller we are done}% -% \shortArrow -% \step{dumuxBlue}{update()}{asImp\_().updateSuccessful()}{updateSuccessful()}{e.g. implicitmodel.hh}% -% {can be filled \modelSpecific}% -% \dummyDistance -% % -% \longArrow{ -% \textnormal{in while(!finished)} -% } -% \step{dumuxBlue}{run()}{problem\_->postTimeStep()}{postTimeStep(),writeOutput()}{implicitproblem.hh}% -% {Give the problem the chance to post-process the solution.}% -% \longArrow{ -% \textnormal{write output}\\ -% \textnormal{uPrev $\leftarrow$ uCur}\\ -% \textnormal{time += dt, timestepIdx++}\\ -% \textnormal{deal with restart and episodes } -% } -% \dummyDistance -% % -% \step{dumuxBlue}{run()$\Rightarrow$setTimeStepSize(problem\_->nextTimeStepSize(dt))\\ -% $\Rightarrow$nextTimeStepSize()} -% {newtonCtl\_.suggestTimestepSize()}{suggestTimestepSize()}{newtoncontroller.hh}% -% {Determine new time step size from number of \textsc{Newton} steps.}% -% \longArrow{ -% \textbf{\color{dumuxBlue}Time step} -% \rightarrow \textbf{\color{black}main}\\ -% \textnormal{loop until simulation is finished} -% } -% -% \end{landscape} -% -% \newpage -% % Original pagestyle (headings and footer) were switched off, -% % in order to get more space for the flowchart. -% \pagestyle{scrheadings} -% \normalsize diff --git a/doc/handbook/4_structure.tex b/doc/handbook/5_structure.tex similarity index 73% rename from doc/handbook/4_structure.tex rename to doc/handbook/5_structure.tex index 228c71fe44eb865fa70fddb43364af9d9d647f47..a4146b5afc4d23dc44248eedb78f7d4ab6cb0192 100644 --- a/doc/handbook/4_structure.tex +++ b/doc/handbook/5_structure.tex @@ -3,19 +3,19 @@ \Dumux has the following folder structure, which is similar to other \Dune modules. \begin{itemize} -\item \texttt{bin}: binaries, e.g. used for the automatic testing, postprocessing, installation +\item \texttt{bin}: binaries, e.g. used for the automatic testing, post-processing, installation \item \texttt{cmake}: the configuration options for building \Dumux \item \texttt{doc}: files necessary for the Doxygen documentation and this handbook, and various logos -\item \texttt{dumux}: the main folder, containing the source files. see \ref{fig:dumux-structure} +\item \texttt{dumux}: the main folder, containing the source files. See \ref{fig:dumux-structure} for a visualized structure. For more information on the models have a look at the Doxygen documentation. \item \texttt{test}: tests for each numerical model and some functionality. - The structure is equivalent to the dumux folder, the \texttt{references} folder - contains solutions for the automatic testing. Each test program consist of source - \texttt{*.cc}, the problem definition \texttt{*problem.hh}, and an input file \texttt{*.input}. + The structure is equivalent to the \texttt{dumux} folder, the \texttt{references} folder + contains solutions for the automatic testing. Each test program consist of a main file + \texttt{main.cc}, the problem definition \texttt{*problem.hh} (specifying initial and boundary + conditions), and an input file \texttt{params.input}. If necessary, spatially dependent parameters are defined in \texttt{*spatialparameters.hh}. For more detailed descriptions of the tests, please have a look at the Doxygen documentation. -\item \texttt{tutorial}: contains the tutorials. \end{itemize} \begin{figure} @@ -71,26 +71,27 @@ [.\node[SecondLevel] {properties}; \node[ThirdLevel] {Base properties for all models.}; ] + [.\node[SecondLevel] {typetraits}; + \node[ThirdLevel] {Helper classes to query type information on compile-time. }; + ] ] [.\node[FirstLevel] {discretization}; -% [.\node[SecondLevel] {\emph{models}}; - \node[ThirdLevel] {Common methods for all discretizations: variable caching, advective and diffusive fluxes, upwinding...}; -% ] - [.\node[SecondLevel] {box}; - \node[ThirdLevel] {Specific files for the box finite volume method: - specifications for advective and diffusive fluxes...}; - ] - [.\node[SecondLevel] {cellcentered}; - \node[ThirdLevel] {Specific files for cell centered finite volume methods.}; - ] - [.\node[SecondLevel] {staggered}; - \node[ThirdLevel] {Specific files for staggered finite volume method.}; + \node[ThirdLevel] {Common methods for all discretizations (box, cell-centered TPFA/MPFA, staggered grid): variable caching, advective and diffusive fluxes, ...}; + ] + [.\node[FirstLevel] {flux}; + [\node[ThirdLevel] { + Collection of classes used to calculate advective and diffusive fluxes.}; ] ] [.\node[FirstLevel] {freeflow}; [.\node[SecondLevel] {\emph{models}}; \node[ThirdLevel] {Single-phase free flow models using Navier-Stokes - and algebraic turbulence models.}; + and eddy-viscosity based Reynolds-averaged Navier-Stokes turbulence models.}; + ] + ] + [.\node[FirstLevel] {geomechanics}; + [.\node[SecondLevel] {\emph{models}}; + \node[ThirdLevel] {Elastic and poro-elastic geomechanics models.}; ] ] [.\node[FirstLevel] {io}; @@ -106,7 +107,7 @@ needed for the constitutive relationships (e.g. Henry coefficient)}; ] [.\node[SecondLevel] {chemistry}; - \node[ThirdLevel] {Files needed to account for, e.g. electrochemical processes as in a fuel cell.}; + \node[ThirdLevel] {Files needed to account for, e.g. electro-chemical processes as in a fuel cell.}; ] [.\node[SecondLevel] {components}; \node[ThirdLevel] {Properties of a pure chemical substance (e.g. water) @@ -126,28 +127,35 @@ ] [.\node[SecondLevel] {fluidstates}; \node[ThirdLevel] {Fluid states are responsible for caching the thermodynamic - configuration of a system at a given spatial and temporal position.}; + configuration of a fluid system at a given spatial and temporal position.}; ] [.\node[SecondLevel] {fluidsystems}; \node[ThirdLevel] {Fluid systems express the thermodynamic relations between quantities.}; ] + [.\node[SecondLevel] {solidstates}; + \node[ThirdLevel] {Solid states are responsible for caching the thermodynamic + configuration of a solid system at a given spatial and temporal position.}; + ] + [.\node[SecondLevel] {solidsystems}; + \node[ThirdLevel] {Solid systems express the thermodynamic properties of a solid.}; + ] [.\node[SecondLevel] {spatialparams}; \node[ThirdLevel] {Base class for all spatially dependent variables, like permeability and porosity. Includes spatial averaging routines. All other properties are specified in the specific files of the respective models.}; ] ] - [.\node[FirstLevel] {mixeddimension}; + [.\node[FirstLevel] {multidomain}; \node[ThirdLevel] { - Coupled model with different dimensions.}; + Common infrastructure to couple multiple domains, models or physics.}; [.\node[SecondLevel] {embedded}; - \node[ThirdLevel] {Embedded mixed dimension method.}; + \node[ThirdLevel] {Embedding of a lower-dimensional model into a higher-dimensional one}; ] [.\node[SecondLevel] {facet}; - \node[ThirdLevel] {Facet mixed dimension method.}; + \node[ThirdLevel] {Mixed-dimensional coupling at facets.}; ] - [.\node[SecondLevel] {glue}; - \node[ThirdLevel] {Grid glue backend.}; + [.\node[SecondLevel] {boundary}; + \node[ThirdLevel] {Coupling at the domain boundaries.}; ] ] [.\node[FirstLevel] {nonlinear}; diff --git a/doc/handbook/5_models.tex b/doc/handbook/6_basics.tex similarity index 64% rename from doc/handbook/5_models.tex rename to doc/handbook/6_basics.tex index 29c0517677c161c5e26932b678b6f44a59999790..a6ec76568a2291ac109ec977457a443ea5635d57 100644 --- a/doc/handbook/5_models.tex +++ b/doc/handbook/6_basics.tex @@ -1,11 +1,14 @@ -\section{Models} +\section{Physical Basics} Here the basic definitions, the general models concept, and a list of -models available in \Dumux are given. +models available in \Dumux are given. The actual differential equations +can be found in the local residuals (see Doxygen documentation of the +model's \texttt{LocalResidual} class). +%TODO: Add more physics \subsection{Basic Definitions and Assumptions} The basic definitions and assumptions are made, using the example of a three-phase three-component system water-NAPL-gas -\cite{A3:class:2002a}. The modification for other multicomponent +\cite{A3:class:2002a}. The modification for other multi-component systems is straightforward and can be found, e.\ g., in \cite{A3:bielinski:2006,A3:acosta:2006}. @@ -122,30 +125,81 @@ $\boldsymbol{v}_\alpha$ & velocity (Darcy or free flow)& & \\ \label{fig:phaseMassEnergyTransfer} \end{figure} + +\subsection{Gas mixing laws} +Prediction of the $p-\varrho-T$ behavior of gas mixtures is typically based on two (contradicting) concepts: Dalton's law or Amagat's law. +In the following the two concepts will be explained in more detail. +% +\subsubsection{Dalton's law} +Dalton's law assumes that the gases in the mixture are non-interacting (with each other) and each gas independently applies its own pressure (partial pressure), the sum of which is the total pressure: +% +\begin{equation} +p = \sum_{i}^{}p_i. +\end{equation} +Here $p_i$ refers to the partial pressure of component i. +As an example, if two equal volumes of gas A and gas B are mixed, the volume of the mixture stays the same but the pressures add up (see Figure \ref{fig:dalton1}). +% +\begin{figure}[ht] + \centering + \includegraphics[width=0.7\textwidth]{png/dalton1.png} + \caption{Dalton's law visualized} + \label{fig:dalton1} +\end{figure} +% +The density of the mixture, $\varrho$, can be calculated as follows: +\begin{equation} +\varrho = \frac{m}{V} = \frac{m_\mathrm{A} + m_\mathrm{B}}{V} = \frac{\varrho_\mathrm{A} V + \varrho_\mathrm{B} V}{V} = \varrho_\mathrm{A} + \varrho_\mathrm{B}, +\end{equation} +% +or for an arbitrary number of gases: +\begin{equation} +\varrho = \sum_{i}^{} \varrho_i ; \quad \varrho_m = \sum_{i}^{} \varrho_{m,i}. +\end{equation} +% +\subsubsection{Amagat's law} +Amagat's law assumes that the volumes of the component gases are additive; the interactions of the different gases are the same as the average interactions of the components. This is known as Amagat's law: +% +\begin{equation} +V = \sum_{i}^{}V_i. +\end{equation} +% +As an example, if two volumes of gas A and B at equal pressure are mixed, the pressure of the mixture stays the same, but the volumes add up (see Figure \ref{fig:dalton2}). +% +\begin{figure}[ht] + \centering + \includegraphics[width=0.7\textwidth]{png/dalton2.png} + \caption{Amagat's law visualized} + \label{fig:dalton2} +\end{figure} +% +The density of the mixture, $\varrho$, can be calculated as follows: +\begin{equation} +\varrho = \frac{m}{V} = \frac{m}{V_\mathrm{A} + V_\mathrm{B}} = \frac{m}{\frac{m_\mathrm{A}}{\varrho_\mathrm{A}} \frac{m_\mathrm{B}}{\varrho_\mathrm{B}}} = +\frac{m}{\frac{X_\mathrm{A} m}{\varrho_\mathrm{A}} \frac{X_\mathrm{B} m}{\varrho_\mathrm{B}}} = \frac{1}{\frac{X_\mathrm{A}}{\varrho_\mathrm{A}} \frac{X_\mathrm{B}}{\varrho_\mathrm{B}}}, +\end{equation} +% +or for an arbitrary number of gases: +% +\begin{equation} +\varrho = \frac{1}{\sum_{i}^{}\frac{X_i}{\varrho_i}} ; \quad \varrho_m = \frac{1}{\sum_{i}^{}\frac{x_i}{\varrho_{m,i}}}. +\end{equation} +% +\subsubsection{Ideal gases} +An ideal gas is defined as a gas whose molecules are spaced so far apart that the behavior of a molecule is not influenced by the presence of other molecules. +This assumption is usually valid at low pressures and high temperatures. The ideal gas law states that, for one gas: +% +\begin{equation} +p = \varrho \frac{RT}{M} ; \quad p= \varrho_m RT. +\end{equation} +% +Using the assumption of ideal gases and either Dalton's law or Amagat's law lead to the density of the mixture, $\varrho$, as: +% +\begin{equation} +\varrho = \frac{p}{RT} \sum_{i}^{}M_i x_i ; \quad \varrho_m = \frac{p}{RT}. +\end{equation} +% \subsection{Available Models} A list of all available models can be found in the Doxygen documentation at \url{http://www.dumux.org/doxygen-stable/html-\DumuxVersion/modules.php}. The documentation includes a detailed description for every model. - -\subsubsection{Temporal discretization} -We discretize time with an explicit or implicit Euler -method. -% TODO: make section with more details on temporal discretization - -\subsubsection{Algorithms to solve equations} -The governing equations of each model can be solved monolithically or sequentially. -The basic idea of the sequential algorithm is to reformulate the -equations of multi-phase flow into one equation for -pressure and equations for phase/component/... transport. The pressure equation -is the sum of the mass balance equations and thus considers the total flow of the -fluid system. The new set of equations is considered as decoupled (or weakly coupled) -and can thus be solved sequentially. The most popular sequential model is the -fractional flow formulation for two-phase flow which is usually implemented applying -an IMplicit Pressure Explicit Saturation algorithm (IMPES). -In comparison to solving the equations monolothically, the sequential structure allows the use of -different discretization methods for the different equations. The standard method -used in the sequential algorithm is a cell-centered finite volume method. Further schemes, -so far only available for the two-phase pressure equation, are cell-centered finite -volumes with multi-point flux approximation (MPFA O-method) and mimetic finite differences. -An $h$-adaptive implementation of both sequential algorithms is provided for two dimensions. diff --git a/doc/handbook/6_inputoutput.tex b/doc/handbook/6_inputoutput.tex new file mode 100644 index 0000000000000000000000000000000000000000..33ad270bcb211a0c9b78530294101e9fa8d7619c --- /dev/null +++ b/doc/handbook/6_inputoutput.tex @@ -0,0 +1,164 @@ +\section{Input and Output} +\label{sec:inputandoutput} + +This section briefly explains grid generation in \Dumux, summarizes +the grid formats that can be used by \Dumux and introduces the \Dumux \texttt{GridManager}. +Finally, this section informs about handling output in \Dumux. + +\subsection{Supported grid file formats} +\Dumux can read grids from file using the Dune Grid Format (DGF), the Gmsh mesh format (MSH), or the Eclipse grid format (GRDECL). +Using the class \texttt{Dumux::VTKReader}, \Dumux has experimental support for reading grids and data from VTK files. + +\subsubsection{Dune Grid Format} +Most of our \Dumux tests use the Dune Grid Format (DGF) to read in grids. A detailed description +of the DGF format and some examples can be found in the \Dune doxygen documentation +\textbf{(Modules $\rightarrow$ I/O $\rightarrow$ Dune Grid Format (DGF)}). To generate larger or more +complex DGF files, we recommend to write your own scripts, e.g, in \Cplusplus, Matlab or Python. + +The DGF format can also be used to read in spatial parameters defined on the grid. These parameters can +be defined on nodes as well as on the elements. An example for predefined parameters on a grid +can be found in \texttt{dumux/test/porousmediumflow/co2/implicit/}. + +\subsubsection{Gmsh Mesh Format} +Gmsh is an open-source flexible grid generator for unstructured finite-element meshes (\cite{GEUZAINE2009}, \url{http://geuz.org/gmsh/}). +\Dumux supports the default Gmsh mesh format (MSH). For the format specifics and how to create grids with Gmsh, e.g., using +the provided GUI, we refer to the Gmsh documentation (\url{http://geuz.org/gmsh/doc/texinfo/gmsh.html}). + +The MSH format can contain element and boundary markers defined on the grid. Thus, boundaries can be easily marked as, e.g., inflow boundaries +using Gmsh. Further, the format supports higher order elements. They can be used to create boundary parametrization supported by, e.g., the grid +manager \texttt{UGGrid}. +An example can be found in \texttt{dumux/test\allowbreak/io/gridmanager}. + +\subsubsection{Eclipse Grid Format} +The Eclipse Grid Format (GRDECL) is commonly used for corner-point grids. +Such grids consist of hexahedra, which are described by eight points on so-called pillars. A special feature of corner-point geometries is that points on pillars can degenerate, meaning that two neighboring points on a pillar can coincide. Furthermore, faces are, in general, bi-linear and cells can be non-convex. This allows for the accurate description of faults, layers, or wells, occurring in geological environments. + +Furthermore, petrophysical properties can be defined (for each cell), by using eclipse-specific keywords, e.g. \texttt{PORO}, \texttt{PERMX}, \texttt{PERMY}. + +\Dumux supports the Eclipse Grid Format by using the \texttt{opm-grid} module (see (\url{https://opm-project.org}). +An example can be found in \texttt{dumux/test\allowbreak/porousmediumflow/2p/implicit/cornerpoint}. + +\subsubsection{Other Grid Formats} +Grid formats other than DGF, MSH, GRDECL, VTK will have to be converted to the DGF, MSH, GRDECL, VTK format before they can be used in \Dumux. +If conversion is not an option, another possibility would be to write your own \texttt{GridManager}s. Examples of other grid formats, +which have previously been either converted or custom-created in \Dumux, are ArtMesh grids (fractured network grids), and ICEM grids (CAD developed grids). + +\subsection{The \Dumux \texttt{GridManager}} +The \texttt{Dumux::GridManager} class constructs the grid from information in the input file and handles the data. +Currently, supported Dune grid interface implementations are \texttt{YaspGrid}, \texttt{OneDGrid}, \texttt{dune-uggrid}, \texttt{dune-alugrid}, \texttt{dune-foamgrid}, \texttt{dune-subgrid}, \texttt{opm-grid} (cornerpoint grids) and \texttt{dune-spgrid}. +Grids can be constructed from a DGF or MSH file by simply providing the filename to the grid in the \texttt{Grid} group~\footnote{Note, +that group name \texttt{Grid} is the default group name and can be customized in your problem changing the string property \texttt{GridParameterGroup}. +This way, it is possible, e.g., for problems with more than one grid, to set different group names for each grid, thus configuring them separately.} +of the input file: +\begin{lstlisting}[style=DumuxParameterFile] +[Grid] +File = mydgfgrid.dgf +\end{lstlisting} + +If you are using an unstructured grid interface like \texttt{UGGrid} or \texttt{ALUGrid}, constructing a grid from a MSH is just changing a line: +\begin{lstlisting}[style=DumuxParameterFile] +[Grid] +File = mygmshgrid.msh +\end{lstlisting} +\Dumux will tell you in case your selected grid manager does not support reading MSH files. + +You want to initially refine your grid? It's just adding a line: +\begin{lstlisting}[style=DumuxParameterFile] +[Grid] +File = mydgfgrid.dgf +Refinement = 4 +\end{lstlisting} + +When reading a MSH file, further parameters are recognized. \texttt{Verbose} enables verbose output on grid construction when set to $1$. +\texttt{BoundarySegments} enables reading parameterized boundaries. \texttt{PhysicalEntities} enables reading boundary and element flags. + +\subsubsection{Parameters specific to the grid implementation} +The \texttt{{Dumux::GridManager}} supports also a selection of parameters that are specific to the chosen grid manager. +To give an example, we take a look at the unstructured grid \texttt{UGGrid}. +\texttt{UGGrid} supports red-green refinement per default. One can turn off the green closure by setting the grid's closure type +\begin{lstlisting}[style=DumuxParameterFile] +[Grid] +File = mydgfgrid.dgf +ClosureType = None # or Green +\end{lstlisting} + +For all available parameters see the Doxygen documentation. + +\subsubsection{Structured grids} +If you want to construct a structured grid without using a specific grid file, insert the following into the input file: +\begin{lstlisting}[style=DumuxParameterFile] +[Grid] +LowerLeft = 0 0 0 +UpperRight = 1 1 1 +Cells = 10 10 20 +\end{lstlisting} +where \texttt{LowerLeft} is a vector to the lower left corner of the grid and \texttt{UpperRight} a vector to the upper right corner. +\texttt{Cells} is a vector with the number of cells in each coordinate direction. Note, that for a grid in a two-dimensional world, the +vectors only have two entries. + +Depending on the grid manager, further parameters are recognized. +\texttt{UGGrid}, for example, supports simplex elements as well as hexahedral elements +(called ``cube'' in \Dune). When creating a structured grid, we can select the cell type as follows +\begin{lstlisting}[style=DumuxParameterFile] +[Grid] +LowerLeft = 0 0 0 +UpperRight = 1 1 1 +Cells = 10 10 20 +CellType = Cube # or Simplex +\end{lstlisting} + +For all available parameters see the Doxygen documentation. + +\subsubsection{Other \Dumux \texttt{GridManager}s} +\begin{itemize} +\item \texttt{CakeGridManager}: Provides a method to create a piece of cake grid. +\item \texttt{CpGridManager}: Reads the GRDECL file and generates a corner-point grid. +\item \texttt{SubgridGridManager}: Creates a \texttt{dune-subgrid} for some given host grid. +\end{itemize} + +\subsection{Input and Output formats} + +\subsubsection{VTK file format} +Dumux allows to write out simulation results via the \texttt{VtkOutputModule}. +For every print-out step, a single VTU file is created. For parallel simulations one file +per print-out step is generated for each processor. +The PVD file groups the single VTU files and contains additionally the time step information. +The VTK file format is supported by common visualisation programs like ParaView, VisIt, and Tecplot. + +\subsubsection{Customize the VTK output} +Using the respective \texttt{initOutputModule} function of the model \texttt{IOFields}, a default +set of variables is stored in the VTK files. It is also possible to add further variables, +using the member function \texttt{addField} of the \texttt{VtkOutputModule}. For example, to add a variable called \texttt{temperatureExact}: +\begin{lstlisting}[style=DumuxCode] +vtkWriter.addField(problem->getExactTemperature(), "temperatureExact"); +\end{lstlisting} + +The first input argument of this method is the value of the additional variable, provided by a method of the corresponding problem. +If it does not already exists, the user has to provide this method. +\begin{lstlisting}[style=DumuxCode] +//! get the analytical temperature +const std::vector& getExactTemperature() +{ + return temperatureExact_; +} +\end{lstlisting} +It is important that the life-time of the added field exceeds the life-time of the writer. That means you can't pass temporaries +to the \texttt{addField} function. The vector has to be stored somewhere, e.g. in the program main file. + +The second input argument is the name of the additional variable (as it should be written in the VTK files). +The example above is taken from: \\ \texttt{test/porousmediumflow/1pnc/implicit/test\_1p2cni\_convection\_fv.cc} + +\subsubsection{VTK as input format} +There is experimental support for reading data and grids from VTK files. Have a look at the \texttt{Dumux::VTKReader} class. + +\subsubsection{Gnuplot interface} +\Dumux provides a small interface to GNUPlot, which can be used to plot results and generate +image files (e.g., png). To use the gnuplot, gnuplot has to be installed. For more information see \ref{gnuplot}. + +\subsubsection{Container I/O} +\Dumux supports writing to file from and reading to some standard \Cplusplus containers like \texttt{std::vector} or \texttt{std::vector}. +If you want to read and write simple vectors, have a look at the header \texttt{dumux/io/container.hh}. + +\subsubsection{Matrix and Vector I/O} +\texttt{dune-istl} supports writing and reading vectors and matrices to/from different format. For example you can write a matrix in a sparse matrix format that +can be read by Matlab (see \texttt{dune/istl/io.hh}). diff --git a/doc/handbook/6_parallel.tex b/doc/handbook/6_parallel.tex new file mode 100644 index 0000000000000000000000000000000000000000..ba4a3580a23b233e01604e2ea43364646d588d3c --- /dev/null +++ b/doc/handbook/6_parallel.tex @@ -0,0 +1,70 @@ +\section{Parallel Computation} +\label{sec:parallelcomputation} +This section explains how \Dumux can be used +on multicore / multinode systems. + +There are different concepts and methods for parallel programming, which are +often grouped in \textit{shared-memory} and \textit{distributed-memory} +approaches. The parallelization in \Dumux is based on the model supported by Dune which is currently based on +\textit{Message Passing Interface} (MPI) (distributed-memory approach). + +The main idea behind the MPI parallelization is the concept of \textit{domain +decomposition}. For parallel simulations, the computational domain is split into +subdomains and one process (\textit{rank}) is used to solve the local problem of each +subdomain. During the global solution process, some data exchange between the +ranks/subdomains is needed. MPI is used to send data to other ranks and to receive +data from other ranks. The domain decomposition in Dune is handled by the grid managers. +The grid is partitioned and distributed on several nodes. Most grid managers contain own domain decomposition methods to split the +computational domain into subdomains. Some grid managers also support external +tools like METIS, ParMETIS, PTScotch or ZOLTAN for partitioning. +On the other hand, linear algebra types such as matrices and vectors +do not know that they are in a parallel environment. Communication is then handled by the components of the +parallel solvers. Currently, the only parallel solver backend is \texttt{Dumux::AMGBackend}, a parallel AMG-preconditioned +BiCGSTAB solver. + +In order for \Dumux simulation to run in parallel, an +MPI library (e.g. OpenMPI, MPICH or IntelMPI) implementation +must be installed on the system. + +\subsection{Prepare a Parallel Application} +Not all parts of \Dumux can be used in parallel. In order to switch to the parallel \texttt{Dumux::AMGBackend} +solver backend include the respective header + +\begin{lstlisting}[style=DumuxCode] +#include +\end{lstlisting} + +Second, the linear solver must be switched to the AMG backend + +\begin{lstlisting}[style=DumuxCode] +using LinearSolver = Dumux::AMGBackend; +\end{lstlisting} + +and the application must be recompiled. The parallel \texttt{Dumux::AMGBackend} instance has to be +constructed with a \texttt{Dune::GridView} object and a mapper, in order to construct the +parallel index set needed for communication. + +\begin{lstlisting}[style=DumuxCode] +auto linearSolver = std::make_shared(leafGridView, fvGridGeometry->dofMapper()); +\end{lstlisting} + +\subsection{Run a Parallel Application} +The starting procedure for parallel simulations depends on the chosen MPI library. +Most MPI implementations use the \textbf{mpirun} command + +\begin{lstlisting}[style=Bash] +mpirun -np +\end{lstlisting} + +where \textit{-np} sets the number of cores (\texttt{n\_cores}) that should be used for the +computation. On a cluster you usually have to use a queuing system (e.g. slurm) to +submit a job. Check with your cluster administrator how to run parallel applications on the cluster. + +\subsection{Handling Parallel Results} +For serial computations, \Dumux produces single vtu-files as default output format. +During a simulation, one VTU file is written for every output step. +In the parallel case, one VTU file for each step and processor is created. +For parallel computations, an additional variable \texttt{"process rank"} is written +into the file. The process rank allows the user to inspect the subdomains +after the computation. The parallel VTU files are combined in a single pvd file +like in sequential simulations that can be opened with e.g. ParaView. diff --git a/doc/handbook/6_propertysystem.tex b/doc/handbook/6_propertysystem.tex new file mode 100644 index 0000000000000000000000000000000000000000..bfe58b3fa3f8779e8c38364541eae359ecbc152a --- /dev/null +++ b/doc/handbook/6_propertysystem.tex @@ -0,0 +1,375 @@ +\section{Property System} +\label{sec:propertysystem} +A high level overview over the property system's design and principle ideas +are given, then follows a reference and a self-contained example. + +\subsection{Motivation and features} +The \Dumux property system is a traits system +which allows easy inheritance. + +In the context of the \Dumux property system, a property is an arbitrary +class body which may contain type definitions, values and methods. + +Just like normal classes, properties can be arranged in hierarchies. In +the context of the \Dumux property system, nodes of the inheritance +hierarchy are called \emph{type tags}. + +It also supports \emph{property nesting}. Property nesting means that the definition of +a property can depend on the value of other properties which may be +defined for arbitrary levels of the inheritance hierarchy. + +\subsection{How-to} +All source files which use the property system should include +the header file \path{dumux/common/propertysystem.hh}. +Declaration of type tags and +property tags as well as defining properties must be done inside the +namespace \texttt{Dumux::Properties}. + +\subsubsection{Defining Type Tags} +New nodes in the type tag hierarchy can be defined in the \texttt{TTag} namespace using +\begin{lstlisting}[style=DumuxCode] +// Create new type tags +namespace TTag { +struct NewTypeTagName { using InheritsFrom = std::tuple; }; +} // end namespace TTag +\end{lstlisting} +where the \texttt{InheritsFrom} alias is optional. To avoid +inconsistencies in the hierarchy, each type tag may be defined only +once for a program. If you call \texttt{GetProp} the property system will first look for the properties defined in \texttt{BaseTagName1} in the \texttt{InheritsFrom} list. +If a defined property is found this property is returned. If no defined property is found the search will continue in the ancestors of \texttt{BaseTagName1}. +If again no defined property is found the search will continue in the second \texttt{BaseTagName2} in the list, and so on. +If no defined property is found at all, a compiler error is triggered. + +\vskip1ex\noindent +Example: +\begin{lstlisting}[style=DumuxCode] +namespace Dumux { +namespace Properties { +namespace TTag { +struct MyBaseTypeTag1 {}; +struct MyBaseTypeTag2 {}; + +struct MyDerivedTypeTag { using InheritsFrom = std::tuple; }; +} // end namespace TTag +}} +\end{lstlisting} + +\subsubsection{Defining new Property Tags} +New property tags are defined using + +\begin{lstlisting}[style=DumuxCode] +template +struct NewPropTagName { using type = UndefinedProperty; }; +\end{lstlisting} + +\vskip1ex\noindent +Example: +\begin{lstlisting}[style=DumuxCode] +namespace Dumux { +namespace Properties { +template +struct MyPropertyTag { using type = UndefinedProperty; }; +}} +\end{lstlisting} + +If you need to forward declare a property use + +\begin{lstlisting}[style=DumuxCode] +// forward declaration +template +struct NewPropTagName; +\end{lstlisting} + +\subsubsection{Defining Properties} +The value of a property on a given node of the type tag hierarchy is +defined using +\begin{lstlisting}[style=DumuxCode] +template +struct PropertyTagName +{ + // arbitrary body of a struct +}; +\end{lstlisting} + +This means a property is defined for a specific type tag node \texttt{TTag::TypeTagName} +by providing a partial template specialization of \texttt{PropertyTagName}. +The body typically contains either the alias \texttt{type}, or a data member \texttt{value}. +However, you can of course write in the body whatever you like. + +\begin{lstlisting}[style=DumuxCode] +template +struct PropertyTagName { using type = type; }; + +template +struct PropertyTagName { static constexpr bool value = booleanValue; }; + +template +struct PropertyTagName { static constexpr int value = integerValue; }; +\end{lstlisting} + +\vskip1ex\noindent +Example: +\begin{lstlisting}[style=DumuxCode] +namespace Dumux { +namespace Properties { + +// Create new type tag +namespace TTag { +struct MyTypeTag {}; +} + +// Define some properties +template struct MyCustomProperty { using type = UndefinedProperty; }; +template struct MyType { using type = UndefinedProperty; }; +template struct MyBoolValue { using type = UndefinedProperty; }; +template struct MyIntValue { using type = UndefinedProperty; }; +template struct MyScalarValue { using type = UndefinedProperty; }; + +// Set the properties for the new type tag +template +struct MyCustomProperty +{ + static void print() + { std::cout << "Hello, World!\n"; } +}; + +template +struct MyType { using type = unsigned int; }; + +template +struct MyBoolValue { static constexpr bool value = true; }; + +template +struct MyIntValue { static constexpr int value = 12345; }; + +template +struct MyScalarValue { static constexpr double value = 12345.67890; }; +}} +\end{lstlisting} + +\subsubsection{Retrieving Property Values} +The type of a property can be retrieved using +\begin{lstlisting}[style=DumuxCode] +using Prop = GetProp; +\end{lstlisting} + +There is a helper struct and a helper function to retrieve the \texttt{type} and \texttt{value} +members of a property + +\begin{lstlisting}[style=DumuxCode] +using PropType = GetPropType; +constexpr auto propValue = getPropValue(); +\end{lstlisting} + +\vskip1ex\noindent +Example:\nolinebreak +\begin{lstlisting}[style=DumuxCode] +template +class MyClass { + // retrieve the ::value attribute of the 'UseMoles' property + static constexpr bool useMoles = getPropValue(); + static constexpr bool useMoles2 = GetProp::value; // equivalent + + // retrieve the ::type attribute of the 'Scalar' property + using Scalar = GetPropType; + using Scalar2 = GetProp::type; // equivalent +}; +\end{lstlisting} + +\subsubsection{Nesting Property Definitions} +Inside property definitions there is access to all other properties +which are defined somewhere on the type tag hierarchy. The node for +which the current property is requested is available via the template argument +\texttt{TypeTag}. Inside property class bodies \texttt{GetPropType} can be used to +retrieve other properties and create aliases. + +\vskip1ex\noindent +Example: +\begin{lstlisting}[style=DumuxCode] +template +struct Vector +{ + using Scalar = GetPropType; + using type = std::vector; +}; +\end{lstlisting} + +\subsection{A Self-Contained Example} +As a concrete example, let us consider some kinds of cars: Compact +cars, sedans, trucks, pickups, military tanks and the Hummer-H1 sports +utility vehicle. Since all these cars share some characteristics, it +makes sense to inherit those from the closest matching car type and +only specify the properties which are different. Thus, an inheritance +diagram for the car types above might look like outlined in Figure +\ref{fig:car-hierarchy}. + +\begin{figure}[t] + \centering + \subfloat[]{ + \begin{tikzpicture} + [cars/.style={rectangle,draw=black,rounded corners,minimum width=2.5cm,node distance=0.5cm}] + % place nodes + \node[cars] (compact) {Compact car}; + \node[cars] (sedan) [below=of compact] {Sedan}; + \node[cars] (truck) [right=of compact] {Truck}; + \node[cars] (pickup) [below right= of sedan] {Pickup}; + \node[cars] (tank) [right=of truck] {Tank}; + \node[cars] (hummer) [below right= of pickup] {Hummer}; + % add edges + \draw [-latex',thick] (compact) -- (sedan); + \draw [-latex',thick] (sedan) -- (pickup); + \draw [-latex',thick] (truck) -- (pickup); + \draw [-latex',thick] (tank) -- (hummer); + \draw [-latex',thick] (pickup) -- (hummer); + \end{tikzpicture} + \label{fig:car-hierarchy} + } + \hspace*{0.5cm} + \subfloat[]{ + \begin{tikzpicture} + [propertyBox/.style={rectangle,draw=black,minimum width=4.5cm,node distance=0.1cm}] + \node[propertyBox] (gasUsage) {GasUsage}; + \node[propertyBox] (speed) [below=of gasUsage] {TopSpeed}; + \node[propertyBox] (seats) [below=of speed] {NumSeats}; + \node[propertyBox] (automatic) [below=of seats] {AutomaticTransmission}; + \node[propertyBox] (calibre) [below=of automatic] {CannonCalibre}; + \node[propertyBox] (payload) [below=of calibre] {Payload}; + \end{tikzpicture} + \label{fig:car-propertynames} + } + \caption{\textbf{(a)}~A possible property inheritance graph for + various kinds of cars. The lower nodes inherit from higher ones; + Inherited properties from nodes on the right take precedence over the + properties defined on the left. \textbf{(b)}~Property names + which make sense for at least one of the car types of (a).} +\end{figure} + +Using the \Dumux property system, this inheritance hierarchy is +defined by: +\begin{lstlisting}[name=propsyscars,style=DumuxCode] +#include +#include + +namespace Dumux { +namespace Properties { +namespace TTag{ +struct CompactCar {}; +struct Truck {}; +struct Tank {}; + +struct Sedan { using InheritsFrom = std::tuple; }; +struct Pickup { using InheritsFrom = std::tuple; }; +struct HummerH1 { using InheritsFrom = std::tuple; }; +}}} // end namespace TTag +\end{lstlisting} + +Figure \ref{fig:car-propertynames} lists a few property names which +make sense for at least one of the nodes of Figure +\ref{fig:car-hierarchy}. These property names can be defined as +follows: +\begin{lstlisting}[name=propsyscars,style=DumuxCode] +template +struct TopSpeed { using type = UndefinedProperty; }; // [km/h] +template +struct NumSeats { using type = UndefinedProperty; }; // [] +template +struct CanonCaliber { using type = UndefinedProperty; }; // [mm] +template +struct GasUsage { using type = UndefinedProperty; }; // [l/100km] +template +struct AutomaticTransmission { using type = UndefinedProperty; }; // true/false +template +struct Payload { using type = UndefinedProperty; }; // [t] +\end{lstlisting} + +\noindent +So far, the inheritance hierarchy and the property names are completely +separate. What is missing is setting some values for the property +names on specific nodes of the inheritance hierarchy. Let us assume +the following: +\begin{itemize} +\item For a compact car, the top speed is the gas usage in $\unitfrac{l}{100km}$ + times $30$, the number of seats is $5$ and the gas usage is + $\unitfrac[4]{l}{100km}$. +\item A truck is by law limited to $\unitfrac[100]{km}{h}$ top speed, the number + of seats is $2$, it uses $\unitfrac[18]{l}{100km}$ and has a cargo payload of + $\unit[35]{t}$. +\item A tank exhibits a top speed of $\unitfrac[60]{km}{h}$, uses $\unitfrac[65]{l}{100km}$ + and features a $\unit[120]{mm}$ diameter canon +\item A sedan has a gas usage of $\unitfrac[7]{l}{100km}$, as well as an automatic + transmission, in every other aspect it is like a compact car. +\item A pick-up truck has a top speed of $\unitfrac[120]{km}{h}$ and a payload of + $\unit[5]{t}$. In every other aspect it is like a sedan or a truck but if in + doubt, it is more like a truck. +\item The Hummer-H1 SUV exhibits the same top speed as a pick-up + truck. In all other aspects it is similar to a pickup and a tank, + but, if in doubt, more like a tank. +\end{itemize} + +\noindent +Using the \Dumux property system, these assumptions are formulated +using +\begin{lstlisting}[name=propsyscars,style=DumuxCode] +template +struct TopSpeed +{static constexpr int value = getPropValue() * 30}; + +template +struct NumSeats { static constexpr int value = 5; }; + +template +struct GasUsage { static constexpr int value = 4; }; + +template +struct TopSpeed { static constexpr int value = 100; }; + +template +struct NumSeats { static constexpr int value = 2; }; + +template +struct GasUsage { static constexpr int value = 18; }; + +template +struct Payload { static constexpr int value = 35; }; + +template +struct TopSpeed { static constexpr int value = 60; }; + +template +struct GasUsage { static constexpr int value = 65; }; + +template +struct CanonCaliber { static constexpr int value = 120; }; + +template +struct GasUsage { static constexpr int value = 7; }; + +template +struct AutomaticTransmission { static constexpr bool value = true; }; + +template +struct TopSpeed { static constexpr int value = 120; }; + +template +struct Payload { static constexpr int value = 5; }; + +template +struct TopSpeed +{ static constexpr int value = getPropValue>(); }; +\end{lstlisting} + +\noindent +Now property values can be retrieved and some diagnostic messages can +be generated. For example +\begin{lstlisting}[name=propsyscars,style=DumuxCode] +int main() +{ + std::cout << "top speed of sedan: " << getPropValue() << "\n"; + std::cout << "top speed of truck: " << getPropValue() << "\n"; +} +\end{lstlisting} +will yield the following output: +\begin{lstlisting}[style=Bash, basicstyle=\ttfamily\scriptsize\let\textcolor\textcolordummy] +$ top speed of sedan: 210 +$ top speed of truck: 100 +\end{lstlisting} diff --git a/doc/handbook/6_spatialdiscretizations.tex b/doc/handbook/6_spatialdiscretizations.tex new file mode 100644 index 0000000000000000000000000000000000000000..48237edcc2aec9472c31df41fe68524d47c29446 --- /dev/null +++ b/doc/handbook/6_spatialdiscretizations.tex @@ -0,0 +1,347 @@ +\section{Spatial Discretization} +\label{spatialdiscretization} + +We discretize space with cell-centered finite volume methods (\ref{cc} ), the box method (\ref{box}) +or a staggered grid scheme (\ref{staggered}). +Grid adaption is available for both box and cell-centered finite volume method. +In general, the spatial parameters, especially the porosity, have to be assigned on +the coarsest level of discretization. +% +\subsection{Cell Centered Finite Volume Methods -- A Short Introduction}\label{cc} +Cell-centered finite volume methods use the elements of the grid as control volumes. +For each control volume the discrete values are determined at the element/control +volume center (not required to be the barycenters). + +We consider a domain $\Omega \subset \mathbb{R}^d$, $d \in \{ 2, 3 \}$ with boundary $\Gamma = \partial \Omega$. Within this section, we consider the following elliptic problem +\begin{equation} + \begin{aligned} + \nabla \cdot \left( - \mathbf{\Lambda} \nabla u \right) &= q &&\mathrm{in} \, \Omega \\ + \left( - \mathbf{\Lambda} \nabla u \right) \cdot \mathbf{n} &= v_N &&\mathrm{on} \, \Gamma_N \\ + u &= u_D &&\mathrm{on} \, \Gamma_D. + \label{eq:elliptic} + \end{aligned} +\end{equation} + +Here, $\mathbf{\Lambda} = \mathbf{\Lambda}(\mathbf{x}, \mathbf{u})$ is a symmetric and positive definite tensor of second rank (e.g. permeability, diffusivity, etc.), $u = u (\mathbf{x})$ is unknown and $q = q(\mathbf{x}, \mathbf{u})$ is a source/sink. +We denote by $\mathcal{M}$ the mesh that results from the division of the domain $\Omega$ into $n_e$ control volumes $K \subset \Omega$. Each $K$ is a polygonal open set such that $K \cap L = \emptyset, \forall{K \neq L}$ and $\overline{\Omega} = \cup_{K \in \mathcal{M}} \overline{K}$. + +For the derivation of the finite-volume formulation we integrate the first equation of \eqref{eq:elliptic} over a control volume $K$ and apply the Gauss divergence theorem: + +\begin{equation} + \int_{\partial K} \left( - \mathbf{\Lambda} \nabla u \right) \cdot \mathbf{n} \, \mathrm{d} \Gamma = \int_K q \, \mathrm{d}x. + \label{eq:ellipticIntegrated} +\end{equation} + +Splitting the control volume boundary $\partial K$ into a finite number of faces $\sigma \subset \partial K$ (such that $\sigma = \overline{K} \cap \overline{L}$ for some neighboring control volume $L$) and replacing the exact fluxes by an approximation, i.e. $F_{K, \sigma} \approx \int_{\sigma} \left( - \mathbf{\Lambda}_K \nabla u \right) \cdot \mathbf{n} \mathrm{d} \Gamma$ (here $\mathbf{\Lambda}_K$ is the value of $\mathbf{\Lambda}$ associated with control volume $K$), yield +\begin{equation} + \sum_{\sigma \subset \partial K} F_{K, \sigma} = Q_K, \quad \forall \, {K \in \mathcal{M}}, +\label{eq:ccdisc} +\end{equation} +where $F_{K, \sigma}$ is the discrete flux through face $\sigma$ flowing out of cell $K$ and $Q_K := \int_K q \, \mathrm{d}x$ is the integrated source/sink term. Equation \eqref{eq:ccdisc} is the typical cell-centered finite-volume formulation. +Finite-volume schemes differ in the way how the term +$(\mathbf{\Lambda}_K \nabla u ) \cdot \mathbf{n} $ is approximated (i.e. the choice of the fluxes $F_{K, \sigma}$). Using the symmetry of the tensor $\mathbf{\Lambda}_K$, this term can be rewritten as +$\nabla u \cdot \mathbf{\Lambda}_K\mathbf{n}$, which corresponds to the directional derivative of $u$ in co-normal direction $\mathbf{\Lambda}_K\mathbf{n}$. +In the following, the main ideas of the two-point flux approximation and the multi-point flux approximation methods are briefly described. Hereby, we restrict the discussion to the two-dimensional case. + +Please also note that other types of equations, e.g. instationary parabolic problems, can be discretized by applying some time discretization scheme to the time derivatives and by using the finite-volume scheme for the flux discretization. For simplicity the discussion is restricted to the elliptic problem \eqref{eq:elliptic}. + +\subsubsection{Tpfa Method}\label{cc_tpfa} +The linear two-point flux approximation is a simple but robust cell-centered finite-volume scheme, which is commonly used in commercial software. +This scheme can be derived by using the co-normal decomposition, which reads +\begin{equation} +\mathbf{\Lambda}_K \mathbf{n}_{K, \sigma} = t_{K,\sigma} \mathbf{d}_{K,\sigma} + \mathbf{d}^{\bot}_{K,\sigma}, \quad t_{K,\sigma} = \frac{\mathbf{n}_{K, \sigma}^T \mathbf{\Lambda}_K \mathbf{d}_{K,\sigma} }{\mathbf{d}_{K,\sigma}^T \mathbf{d}_{K,\sigma}}, \; \mathbf{d}^{\bot}_{K,\sigma} = \mathbf{\Lambda}_K \mathbf{n}_{K, \sigma} - t_{K,\sigma} \mathbf{d}_{K,\sigma}, +\label{eq:conormalDecTpfa} +\end{equation} +with the tensor $\mathbf{\Lambda}_K$ associated with control volume $K$, the distance vector $\mathbf{d}_{K,\sigma} := \mathbf{x}_\sigma - \mathbf{x}_K$ and $\mathbf{d}_{K,\sigma}^T \mathbf{d}^{\bot}_{K,\sigma} = 0$, see Figure \ref{pc:cctpfa} for the used notations. The same can be done for the conormal $\mathbf{\Lambda}_L \mathbf{n}_{L, \sigma}$. The $t_{K,\sigma}$ and $t_{L,\sigma}$ are the transmissibilities associated with the face $\sigma$. These transmissibilities are calculated in \Dumux by using the function \texttt{computeTpfaTransmissibility}. + +\begin{figure} [ht] +\centering +\includegraphics[width=0.4\linewidth,keepaspectratio]{png/cctpfa.png} +\caption{Two neighboring control volumes sharing the face $\sigma$.} +\label{pc:cctpfa} +\end{figure} + + +With these notations, it follows that for each cell $K$ and face $\sigma$ +\begin{equation} +\nabla u \cdot \mathbf{\Lambda}_K \mathbf{n}_{K, \sigma} = t_{K,\sigma} \nabla u \cdot \mathbf{d}_{K,\sigma} + \nabla u \cdot \mathbf{d}^{\bot}_{K,\sigma}. +\end{equation} +For the Tpfa scheme, the second part in the above equation is neglected. By using the fact that $\nabla u \cdot \mathbf{d}_{K,\sigma} \approx u_\sigma - u_K$, the discrete fluxes for face $\sigma$ are given by +\begin{equation} +F_{K,\sigma} = -\meas{\sigma} t_{K,\sigma} (u_\sigma - u_K), \qquad F_{L,\sigma} = -\meas{\sigma} t_{L,\sigma} (u_\sigma - u_L). +\label{eq:TPFAOneSided} +\end{equation} +Enforcing local flux conservation, i.e. $F_{K,\sigma}+F_{L,\sigma}=0$, results in +\begin{equation} +u_\sigma = \frac{t_{K,\sigma} u_K + t_{L,\sigma} u_L}{t_{K,\sigma} + t_{L,\sigma}}. +\end{equation} +With this, the fluxes \eqref{eq:TPFAOneSided} are rewritten as +\begin{equation} +F_{K,\sigma} = \meas{\sigma} \frac{t_{K,\sigma} t_{L,\sigma}}{t_{K,\sigma} + t_{L,\sigma}} (u_K - u_L), \quad F_{L,\sigma} = \meas{\sigma} \frac{t_{K,\sigma} t_{L,\sigma}}{t_{K,\sigma} + t_{L,\sigma}} (u_L - u_K). +\label{eq:TPFAFlux} +\end{equation} +By neglecting the orthogonal term, the consistency of the scheme is lost for general grids, where $\nabla u \cdot \mathbf{d}^{\bot}_{K,\sigma} \not = 0$. The consistency is achieved only for so-called K-orthogonal grids for which $\mathbf{d}^{\bot}_{K,\sigma} = 0$. For such grids we deduce that +\begin{equation} +\frac{t_{K,\sigma} t_{L,\sigma}}{t_{K,\sigma} + t_{L,\sigma}} = \frac{\tau_{K,\sigma} \tau_{L,\sigma}}{\tau_{K,\sigma} d_{L,\sigma} + \tau_{L,\sigma} d_{K,\sigma}}, +\label{eq:TPFAcoeffNew} +\end{equation} +with $\tau_{K,\sigma} := \mathbf{n}_{K, \sigma} \mathbf{\Lambda}_K\mathbf{n}_{K, \sigma}, \tau_{L,\sigma} := \mathbf{n}_{L, \sigma} \mathbf{\Lambda}_L\mathbf{n}_{L, \sigma}$, $d_{K,\sigma}:= \mathbf{n}_{K, \sigma} \cdot \mathbf{d}_{K, \sigma}$, and $d_{L,\sigma}:= \mathbf{n}_{L, \sigma} \cdot \mathbf{d}_{L, \sigma}$. This reduces, for the case of scalar permeability, to a distance weighted harmonic averaging of permeabilities. + + + +\subsubsection{Mpfa Method}\label{cc_mpfa} +Expressions for the face fluxes $F_{K, \sigma}$ are obtained by introducing intermediate face unknowns $u_\sigma$ in addition to the cell unknowns $u_K$ and enforcing the physically motivated continuity of fluxes and continuity of the solution across the faces. For a face $\sigma$ between the two polygons $K$ and $L$ these conditions read: +\begin{equation} + \begin{aligned} + &F_{K, \sigma} + F_{L, \sigma} = 0 \\ + &{u}_{K,\sigma} = {u}_{L,\sigma} = {u}_{\sigma}. + \label{eq:sigmaConditions} + \end{aligned} +\end{equation} +Using these conditions, the intermediate face unknowns ${u}_\sigma$ can be eliminated and the fluxes are expressed as a function of the cell unknowns $u_N$ and associated transmissibilities $t^N_{K,\sigma}$: + +\begin{equation} + F_{K,\sigma} = \sum_{N \in \mathcal{S}_{K,\sigma}} t^N_{K,\sigma} u_{N}. + \label{eq:FVFluxExpression} +\end{equation} + +\begin{figure} [ht] +\centering +\includegraphics[width=0.8\linewidth,keepaspectratio]{pdf/mpfa_iv.pdf} +\caption{Interaction region for the Mpfa-O method. The graphic on the right illustrates how the sub-control volume $L^v$ and face $\sigma^v_2$ are embedded in cell $L$. Note that the face stencils for all sub-control volume faces in the depicted interaction region are $\mathcal{S}_{\sigma^v_i} = \{ K,L,M \}$, meaning that the fluxes over the sub-control volume faces depend on the three cell unknowns $u_K, u_L, u_M$.} +\label{pc:interactionRegion_mpfa} +\end{figure} + +The main difference between the various finite-volume schemes available is the assembly of the face fluxes, i.e. the computation of the $t^N_{K,\sigma}$ and the size of $\mathcal{S}_{K,\sigma}$. For the Tpfa, that has been presented in the last section, the stencil and transmissibilities are given as +\begin{equation*} +\mathcal{S}_{K,\sigma} = \lbrace K,L \rbrace, \quad t^K_{K,\sigma} = \meas{\sigma} \frac{t_{K,\sigma} t_{L,\sigma}}{t_{K,\sigma} + t_{L,\sigma}},\; t^L_{K,\sigma} = -\meas{\sigma} \frac{t_{K,\sigma} t_{L,\sigma}}{t_{K,\sigma} + t_{L,\sigma}}, +\end{equation*} +with $t_{K,\sigma},t_{L,\sigma}$ as defined in equation \eqref{eq:conormalDecTpfa}. + +In the following, a multi-point flux approximation method (Mpfa-O method), which was introduced in \citet{A3:aavatsmark:2002}, is presented. The main difference to the Tpfa scheme is the fact that a consistent discrete gradient is constructed, i.e. the term $\nabla u \cdot \mathbf{d}^{\bot}_{K,\sigma}$ is not neglected. + +For this scheme, a dual grid is created by connecting the barycenters of the cells with the barycenters of the faces ($d=2$) or the barycenters of the faces and edges ($d=3$). This divides each cell into sub-control volumes $K^v$. Analogously, each face is sub-divided into sub-control volume faces $\sigma^v$, see Figure \ref{pc:interactionRegion_mpfa}. We allow for piecewise constant $\mathbf{\Lambda}$ (denoted as $\mathbf{\Lambda}_K$ for each cell $K$) and construct discrete gradients $\nabla_\mathcal{D}^{K^v} u$ (per sub-control volume $K^v$). +In the following, we restrict our discussion to the two-dimensional setup that is shown in Figure \ref{pc:interactionRegion_mpfa}. +Here, the discrete gradients are constructed to be consistent such that the following conditions hold: +\begin{equation} +\nabla_\mathcal{D}^{K^v} u \cdot (\mathbf{x}_{\sigma^v_1}- \mathbf{x}_{K}) = u_{\sigma^v_1} - u_K, \quad \nabla_\mathcal{D}^{K^v} u \cdot (\mathbf{x}_{\sigma^v_3}- \mathbf{x}_{K}) = u_{\sigma^v_3} - u_K. +\end{equation} +Thus, a discrete gradient (for sub-control volume $K^v$) that fulfills these conditions is given as +\begin{equation} +\nabla_\mathcal{D}^{K^v} u = \mathbb{D}^{-T}_{K^v} + \begin{bmatrix} + u_{\sigma^v_1} - u_K \\ + u_{\sigma^v_3} - u_K + \end{bmatrix}, \qquad \text{ with }\; \mathbb{D}_{K^v} := + \begin{bmatrix} + \mathbf{x}_{\sigma^v_1}- \mathbf{x}_K & \mathbf{x}_{\sigma^v_3} - \mathbf{x}_K + \end{bmatrix}. + \label{eq:MPFAGradientRecons} +\end{equation} + +This enables us to write the discrete flux across $\sigma^v_1$ from cell $K$ as follows: +\begin{equation} + F_{K, \sigma^v_1} := - |\sigma^v_1| \mathbf{n}_{\sigma^v_1}^T \mathbf{\Lambda}_K \nabla_\mathcal{D}^{K^v} u. + \label{eq:discreteFlux} +\end{equation} +Inserting the discrete gradient, yields +\begin{equation} + F_{K, \sigma^v_1} = \omega_{K,\sigma^v_1\sigma^v_1}(u_K - u_{\sigma^v_1}) + \omega_{K,\sigma^v_1 \sigma^v_3}(u_K - u_{\sigma^v_3}), + \label{eq:discreteFluxRef} +\end{equation} +with $(\omega_{K,\sigma^v_1\sigma^v_1},\omega_{K,\sigma^v_1 \sigma^v_3})^T = |\sigma^v_1| \mathbb{D}^{-1}_{K^v}\mathbf{\Lambda}_K \mathbf{n}_{\sigma^v_1}$. These values are calculated in \Dumux by using the function \texttt{computeMpfaTransmissibility}. +\\ \ \\ +To deduce a cell-centered scheme, the introduced face unknowns $u_{\sigma^v_i}$ have to be eliminated. This is done by enforcing flux continuity for each sub-control volume face, i.e. +\begin{align} +F_{K, \sigma^v_1} + F_{L, \sigma^v_1} &= 0, \\ F_{K, \sigma^v_3} + F_{M, \sigma^v_3} &= 0, \\ F_{L, \sigma^v_2} + F_{M, \sigma^v_2} &= 0. +\end{align} +This results in a system of equations for the face unknowns $\mathbf{u}_{\sigma}$ +\begin{equation} +\mathbb{A}^{3\times 3} \mathbf{u}_{\sigma} = \mathbb{B}^{3\times 3} \mathbf{u}, +\end{equation} +where $\mathbf{u}$ contains the three cell unknowns $u_K,u_L,u_M$ and $\mathbf{u}_{\sigma}$ the three face unknowns $u_{\sigma^v_1}, u_{\sigma^v_2}, u_{\sigma^v_3}$. +Inserting these face unknowns into the flux expression \eqref{eq:discreteFluxRef} yields +\begin{equation} + F_{K,\sigma^v_i} = \sum_{N \in \lbrace K,L,M \rbrace } t^N_{K,\sigma^v_i} u_{N} = \mathbf{t}_{K,\sigma^v_i} \cdot \mathbf{u}, + \label{eq:FVFluxExpressionSubFace} +\end{equation} +for each cell $K$ and sub-control volume face $\sigma^v_i$. +% +% +\subsection{Box Method -- A Short Introduction}\label{box} + +The so called box method unites the advantages of the finite-volume (FV) and +finite-element (FE) methods. + +First, the model domain $\Omega$ is discretized with a FE mesh consisting of nodes +$i$ and corresponding elements $E_k$. Then, a secondary FV mesh is constructed +by connecting the midpoints and barycenters of the elements surrounding node +$i$ creating a box $B_i$ around node $i$ (see Figure \ref{pc:box}a). + +\begin{figure} [ht] +\includegraphics[width=0.8\linewidth,keepaspectratio]{png/box_disc.png} +\caption{\label{pc:box} Discretization of the box method} +\end{figure} + +The FE mesh divides the box $B_i$ into subcontrolvolumes (scv's) $b^k_i$ +(see Figure \ref{pc:box}b). Figure \ref{pc:box}c shows the finite element $E_k$ +and the scv's $b^k_i$ inside $E_k$, which belong to four different boxes $B_i$. +Also necessary for the discretization are the faces of the subcontrolvolumes (scvf's) +$e^k_{ij}$ between the scv's $b^k_i$ and $b^k_j$, where $|e^k_{ij}|$ is the length +of the scvf. The integration points $x^k_{ij}$ on $e^k_{ij}$ and the outer normal +vector $\mathbf n^k_{ij}$ are also to be defined (see Figure \ref{pc:box}c). + +The advantage of the FE method is that unstructured grids can be used, while the +FV method is mass conservative. The idea is to apply the FV method (balance of +fluxes across the interfaces) to each FV box $B_i$ and to get the fluxes across +the interfaces $e^k_{ij}$ at the integration points $x^k_{ij}$ from the FE approach. +Consequently, at each scvf the following expression results: + +\begin{equation} + f(\tilde u(x^k_{ij})) \cdot \mathbf n^k_{ij} \: |e^k_{ij}| \qquad \textrm{with} + \qquad \tilde u(x^k_{ij}) = \sum_i N_i(x^k_{ij}) \cdot \hat u_i . +\end{equation} + +In the following, the discretization of the balance equation is going to be derived. +From the \textsc{Reynolds} transport theorem follows the general balance equation: + +\begin{equation} + \underbrace{\int_\Omega \frac{\partial}{\partial t} \: u \, \mathrm{d}x}_{1} + + \underbrace{\int_{\partial\Omega} (\mathbf{v} u + \mathbf w) \cdot \textbf n \, \mathrm{d}\Gamma}_{2} = \underbrace{\int_\Omega q \, \mathrm{d}x}_{3} +\end{equation} + +\begin{equation} + f(u) = \int_\Omega \frac{\partial u}{\partial t} \, \mathrm{d}x + \int_{\Omega} \nabla \cdot + \underbrace{\left[ \mathbf{v} u + \mathbf w(u)\right] }_{F(u)} \, \mathrm{d}x - \int_\Omega q \, \mathrm{d}x = 0 +\end{equation} +where term 1 describes the changes of entity $u$ within a control volume over +time, term 2 the advective, diffusive and dispersive fluxes over the interfaces +of the control volume and term 3 is the source and sink term. $\Omega$ denotes the +model domain and $F(u) = F(\mathbf v, p) = F(\mathbf v(x,t), p(x,t))$. + +Like the FE method, the box method follows the principle of weighted residuals. +In the function $f(u)$ the unknown $u$ is approximated by discrete values at the +nodes of the FE mesh $\hat u_i$ and linear basis functions $N_i$ yielding an +approximate function $f(\tilde u)$. For $u\in \lbrace \mathbf v, p, x^\kappa \rbrace$ +this means: + +\begin{minipage}[b]{0.47\textwidth} +\begin{equation} +\label{eq:p} + \tilde p = \sum_i N_i \hat{p}_i +\end{equation} +\begin{equation} +\label{eq:v} + \tilde{\mathbf v} = \sum_i N_i \hat{\mathbf v}_i +\end{equation} +\begin{equation} +\label{eq:x} + \tilde x^\kappa = \sum_i N_i \hat x_i^\kappa +\end{equation} +\end{minipage} +\hfill +\begin{minipage}[b]{0.47\textwidth} +\begin{equation} +\label{eq:dp} + \nabla \tilde p = \sum_i \nabla N_i \hat{p}_i +\end{equation} +\begin{equation} +\label{eq:dv} + \nabla \tilde{\mathbf v} = \sum_i \nabla N_i \hat{\mathbf v}_i +\end{equation} +\begin{equation} +\label{eq:dx} + \nabla \tilde x^\kappa = \sum_i \nabla N_i \hat x_i^\kappa . +\end{equation} +\end{minipage} + +Due to the approximation with node values and basis functions the differential +equations are not exactly fulfilled anymore but a residual $\varepsilon$ is produced. + +\begin{equation} + f(u) = 0 \qquad \Rightarrow \qquad f(\tilde u) = \varepsilon +\end{equation} + +Application of the principle of weighted residuals, meaning the multiplication +of the residual $\varepsilon$ with a weighting function $W_j$ and claiming that +this product has to vanish within the whole domain, + +\begin{equation} + \int_\Omega \varepsilon W_j \, \mathrm{d}x \overset {!}{=} \: 0 \qquad \textrm{with} \qquad \sum_j W_j =1 +\end{equation} +yields the following equation: + +\begin{equation} + \int_\Omega \frac{\partial \tilde u}{\partial t} W_j \, \mathrm{d}x + \int_\Omega + \left[ \nabla \cdot F(\tilde u) \right] W_j \, \mathrm{d}x - \int_\Omega q W_j \, \mathrm{d}x = \int_\Omega \varepsilon W_j \, \mathrm{d}x \: \overset {!}{=} \: 0. +\label{eq:weightedResidual} +\end{equation} + +For standard Galerkin schemes, the weighting functions $W_j$ are chosen the same as the ansatz functions $N_j$. However, this does not yield a locally mass-conservative scheme. +Therefore, for the Box method, the weighting functions $W_j$ are chosen as +the piece-wise constant functions over a +control volume box $B_j$, i.e. + +\begin{equation} + W_j(x) = \begin{cases} + 1 &x \in B_j \\ + 0 &x \notin B_j.\\ + \end{cases} +\label{eq:weightingFunctions} +\end{equation} +Thus, the Box method is a Petrov-Galerkin scheme, where the weighting functions do not belong to the same function space than the ansatz functions. + +Inserting definition \eqref{eq:weightingFunctions} into equation \eqref{eq:weightedResidual} and using the \textsc{Green-Gaussian} integral theorem results in +\begin{equation} + \int_{B_j} \frac{\partial \tilde u}{\partial t} \, \mathrm{d}x + \int_{\partial B_j} F(\tilde u) \cdot \mathbf n \, \mathrm{d}\Gamma_{B_j} - \int_{B_j} q \, \mathrm{d}x \overset {!}{=} \: 0, +\label{eq:BoxMassBlance} +\end{equation} +which has to hold for every box $B_j$. + +The first term in equation \eqref{eq:BoxMassBlance} can be written as +\begin{equation} +\int_{B_j} \frac{\partial \tilde u}{\partial t} \, \mathrm{d}x = \frac{d}{dt} \int_{B_j} \sum_i \hat u_i N_i \, \mathrm{d}x = \sum_i \frac{\partial \hat u_i}{\partial t} \int_{B_j} N_i \, \mathrm{d}x. +\end{equation} +Here, a mass lumping technique is applied by assuming that the storage capacity is +reduced to the nodes. This means that the integrals $M_{i,j} = \int_{B_j} N_i \, \mathrm{d}x$ +are replaced by some mass lumped terms $M^{lump}_{i,j}$ which are defined as +\begin{equation} + M^{lump}_{i,j} =\begin{cases} |B_j| &j = i\\ + 0 &j \neq i,\\ + \end{cases} +\end{equation} +where $|B_j|$ is the volume of the FV box $B_j$ associated with node $j$. +The application of this assumption yields + +\begin{equation} +\label{eq:disc1} + |B_j| \frac{\partial \hat u_j}{\partial t} + + \int_{\partial B_j} F(\tilde u) \cdot \mathbf n \, \mathrm{d}\Gamma_{B_j} - Q_j = 0, +\end{equation} +where $Q_j$ is an approximation (using some quadrature rule) of the integrated source/sink term $\int_{B_j} q \, \mathrm{d}x$. + +Using an implicit Euler time discretization finally +leads to the discretized form which will be applied to the mathematical +flow and transport equations: + +\begin{equation} +\label{eq:discfin} + |B_j| \frac{\hat u_j^{n+1} - \hat u_j^{n}}{\Delta t} + + \int_{\partial B_j} F(\tilde u^{n+1}) \cdot \mathbf n + \; \mathrm{d}\Gamma_{B_j} - Q_j^{n+1} \: = 0. +\end{equation} +Equation \eqref{eq:discfin} has to be fulfilled for each box $B_j$. +% +\subsection{Staggered Grid -- A Short Introduction}\label{staggered} + +\begin{figure}[ht] +\centering +\includegraphics[width=.8\linewidth]{./pdf/staggered_grid.pdf} +\caption{\label{pc:staggered} Discretization of the staggered-grid method. The figure shows the different control volume arrangements, which are staggered with respect to each other. There are the control volumes centered around the scalar primary variables in black, the control volumes located around the $x$-component of the velocity in blue and the control volumes located around the $y$-components of the velocity in red. The control volume boundaries are given by lines. Additionally, there is one shaded example control volume each.\\ +In the two-dimensional free-flow models, the continuity equation is discretized using the black control volumes, the $x$-component of the momentum equation is discretized using the blue control volumes and the $y$-component is discretized using the red control volumes. In three dimensions this works analogously.} +\end{figure} + +The staggered-grid or marker-and-cell method uses a finite volume method with different control volumes for different equations. There are control volumes centered around the scalar primary variables. They correspond to the finite volume mesh. Additionally, there are control volumes located around the $x,y$ and (in 3D) $z$ velocity components which are shifted in the $x,y$ and $z$ direction, such that the velocity components are located on the edges of the cell-centered finite volume mesh (see Figure~\ref{pc:staggered}). As for the cell-centered method, the fluxes are evaluated at the edges of each control volume with a two-point flux approximation, cf. \ref{cc}.\par +The staggered-grid method is robust, mass conservative, and free of pressure oscillations +but should, as the cell-centered TPFA method, only be applied for structured grids. +Currently, all free-flow models in \Dumux use the staggered-grid discretization. diff --git a/doc/handbook/6_stepsofasimulation.tex b/doc/handbook/6_stepsofasimulation.tex new file mode 100644 index 0000000000000000000000000000000000000000..7ac80d80dc4be8e87c5d9a3dc70e82d3ffd0b40d --- /dev/null +++ b/doc/handbook/6_stepsofasimulation.tex @@ -0,0 +1,64 @@ +\section{Steps of a \Dumux Simulation} +\label{flow} + + +This chapter is supposed to give a short overview over how things are ``handed around'' in \Dumux. It +is not a comprehenisve guide through the modeling framework of \Dumux, but +hopefully it will help getting to grips with it. + +In Section \ref{content} the structure of \Dumux is shown from a \emph{content} +point of view. + +\subsection{Structure -- by Content} + +\label{content} +In Figure \ref{fig:algorithm}, the algorithmic representations of a monolithical +solution scheme is illustrated down to the element level. + +\begin{figure}[hbt] +\setcounter{thingCounter}{0} + +\scriptsize +\sffamily +\begin{center}\parbox{0cm}{ +\begin{tabbing} +\textbf{{\begin{turn}{45}\color{black}\numberThis{main}{init}\end{turn}}} \= +\textbf{{\begin{turn}{45}\color{dumuxBlue}\numberThis{time step}{prep}\end{turn}}} \= +\textbf{{\begin{turn}{45}\color{Mulberry}\numberThis{\textsc{Newton}}{elem}\end{turn}}} \= +\textbf{{\begin{turn}{45}\color{dumuxYellow}\numberThis{element}{calc}\end{turn}}} \= \\ +\\ +\color{black}initialize \\ +\color{black}\textbf{foreach} time step\\ + + \> \color{dumuxBlue}\textbf{foreach} \textsc{Newton} iteration \\ + + \> \> \color{Mulberry}\textbf{foreach} element \\ + + \> \> \> \color{dumuxYellow}- calculate element \\ + \> \> \> \color{dumuxYellow}\; residual vector and \\ + \> \> \> \color{dumuxYellow}\; Jacobian matrix\\ + \> \> \> \color{dumuxYellow}- assemble into global\\ + \> \> \> \color{dumuxYellow}\; residual vector and \\ + \> \> \> \color{dumuxYellow}\;{Jacobian} matrix \\ + + \> \> \color{Mulberry}\textbf{endfor} \\ + + \> \> \color{Mulberry}solve linear system\\ + \> \> \color{Mulberry}update solution\\ + \> \> \color{Mulberry}check for \textsc{Newton} convergence\\ + \> \color{dumuxBlue}\textbf{endfor}\\ + \> \color{dumuxBlue}- adapt time step size, \\ + \> \color{dumuxBlue}\; possibly redo with smaller step size\\ + \> \color{dumuxBlue}- write result\\ +\color{black}\textbf{endfor}\\ +\color{black}finalize +\end{tabbing}} +\end{center} +\caption{Structure of a monolithical solution scheme in \Dumux.} +\label{fig:algorithm} +\end{figure} + +\subsection{Structure -- by Implementation} +A possible starting point to understand how the above mentioned algorithm is implemented within \Dumux, +is the example main file +\url{https://git.iws.uni-stuttgart.de/dumux-repositories/dumux-course/releases/3.0/exercises/exercise-mainfile/exercise_1p_a.cc} diff --git a/doc/handbook/6_temporaldiscretizations.tex b/doc/handbook/6_temporaldiscretizations.tex new file mode 100644 index 0000000000000000000000000000000000000000..fd424205bd1065597c4113cc34e2d2bd661a116e --- /dev/null +++ b/doc/handbook/6_temporaldiscretizations.tex @@ -0,0 +1,62 @@ +\section{Temporal Discretization and Solution Strategies} +%TODO: Intro sentences +\subsection{Temporal discretization} + +Our systems of partial differential equations are discretized in space and in time. + +Let us consider the general case of a balance equation of the following form +\begin{equation}\label{eq:generalbalance} +\frac{\partial m(u)}{\partial t} + \nabla\cdot\mathbf{f}(u, \nabla u) + q(u) = 0, +\end{equation} +seeking an unknown quantity $u$ in terms of storage $m$, flux $\mathbf{f}$ and source $q$. +All available Dumux models can be written mathematically in form of \eqref{eq:generalbalance} +with possibly vector-valued quantities $u$, $m$, $q$ and a tensor-valued flux $\mathbf{f}$. +For the sake of simplicity, we assume scalar quantities $u$, $m$, $q$ and a vector-valued +flux $\mathbf{f}$ in the notation below. + +For discretizing \eqref{eq:generalbalance} we need to choose an +approximation for the temporal derivative $\partial m(u)/\partial t$. +While many elaborate methods for this approximation exist, +we focus on the simplest one of a first order difference quotient +\begin{equation}\label{eq:euler} +\frac{\partial m(u_{k/k+1})}{\partial t} +\approx \frac{m(u_{k+1}) - m(u_k)}{\Delta t_{k+1}} +\end{equation} +for approximating the solution $u$ at time $t_k$ (forward) or $t_{k+1}$ (backward). +The question of whether to choose the forward or the backward quotient leads to the +explicit and implicit Euler method, respectively. +In case of the former, inserting \eqref{eq:euler} in \eqref{eq:generalbalance} +at time $t_k$ leads to +\begin{equation}\label{eq:expliciteuler} +\frac{m(u_{k+1}) - m(u_k)}{\Delta t_{k+1}} + \nabla\cdot\mathbf{f}(u_k, \nabla u_k) + q(u_k) = 0, +\end{equation} +whereas the implicit Euler method is described as +\begin{equation}\label{eq:impliciteuler} +\frac{m(u_{k+1}) - m(u_k)}{\Delta t_{k+1}} ++ \nabla\cdot\mathbf{f}(u_{k+1}, \nabla u_{k+1}) + q(u_{k+1}) = 0. +\end{equation} +Once the solution $u_k$ at time $t_k$ is known, it is straightforward +to determine $m(u_{k+1})$ from \eqref{eq:expliciteuler}, +while attempting to do the same based on \eqref{eq:impliciteuler} +involves the solution of a system of equations. +On the other hand, the explicit method \eqref{eq:expliciteuler} is stable only +if the time step size $\Delta t_{k+1}$ is below a certain limit that depends +on the specific balance equation, whereas the implicit method \eqref{eq:impliciteuler} +is unconditionally stable. + +\subsection{Solution strategies to solve equations} +The governing equations of each model can be solved monolithically or sequentially. +The basic idea of the sequential algorithm is to reformulate the +equations of multi-phase flow into one equation for +pressure and equations for phase/component/... transport. The pressure equation +is the sum of the mass balance equations and thus considers the total flow of the +fluid system. The new set of equations is considered as decoupled (or weakly coupled) +and can thus be solved sequentially. The most popular sequential model is the +fractional flow formulation for two-phase flow which is usually implemented applying +an IMplicit Pressure Explicit Saturation algorithm (IMPES). +In comparison to solving the equations monolithically, the sequential structure allows the use of +different discretization methods for the different equations. The standard method +used in the sequential algorithm is a cell-centered finite volume method. Further schemes, +so far only available for the two-phase pressure equation, are cell-centered finite +volumes with multi-point flux approximation (Mpfa-O method) and mimetic finite differences. +An $h$-adaptive implementation of both sequential algorithms is provided for two dimensions. diff --git a/doc/handbook/CMakeLists.txt b/doc/handbook/CMakeLists.txt index c2e68c339175cc825cda443391e8cf5348d79739..f5eae6367b966443548d53245afe55a165ef3ef2 100644 --- a/doc/handbook/CMakeLists.txt +++ b/doc/handbook/CMakeLists.txt @@ -1,51 +1,52 @@ +if(NOT (${DUNE_COMMON_VERSION} VERSION_LESS "2.7")) +# use latexmk +dune_add_latex_document( + SOURCE 0_dumux-handbook.tex + FATHER_TARGET doc + INSTALL ${CMAKE_INSTALL_DOCDIR}/doc/handbook) + +else() +# use UseLATEX.cmake set(TEX_INPUTS 0_dumux-handbook.tex 0_listingstyle.tex 1_introduction.tex - 2_detailedinstall.tex 2_quickinstall.tex - 3_tutorial.tex - 3_furtherpractice.tex - 4_assemblinglinearsystem.tex - 4_guidelines.tex - 4_developingdumux.tex - 4_externaltools.tex - 4_newfoldersetup.tex - 4_parameterfiles.tex - 4_restartsimulations.tex - 4_structure.tex - 5_stepsofasimulation.tex - 5_grids.tex - 5_models.tex - 5_propertysystem.tex - 5_spatialdiscretizations.tex + 3_detailedinstall.tex + 4_course.tex + 4_furtherpractice.tex + 5_assemblinglinearsystem.tex + 5_developingdumux.tex + 5_externaltools.tex + 5_newfoldersetup.tex + 5_parameterfiles.tex + 5_restartsimulations.tex + 5_structure.tex + 6_basics.tex + 6_inputoutput.tex + 6_parallel.tex + 6_propertysystem.tex + 6_spatialdiscretizations.tex + 6_stepsofasimulation.tex + 6_temporaldiscretizations.tex installDumux.sh) set(TEX_IMAGES - PNG/box_disc.png - PNG/cc_disc.png - PNG/dumux_strucutre_flowchart_horizontal_explained.png - PNG/dunedesign.png - ../logo/dumux_logo_hires_whitebg.png) + png/box_disc.png + png/cctpfa.png + png/dumux_strucutre_flowchart_horizontal_explained.png + png/dunedesign.png + ../logo/dumux_logo_hires_whitebg.png + png/dalton1.png + png/dalton2.png + pdf/staggered_grid.pdf + pdf/mpfa_iv.pdf) -if(DUNE_COMMON_VERSION VERSION_LESS 2.5) - # this only works before Dune 2.5 - dune_add_latex_document(0_dumux-handbook.tex - FATHER_TARGET doc - DEFAULT_PDF - BIBFILES dumux-handbook.bib - INPUTS ${TEX_INPUTS} - IMAGES ${TEX_IMAGES}) - - create_doc_install(${CMAKE_CURRENT_BINARY_DIR}/0_dumux-handbook.pdf - ${CMAKE_INSTALL_DOCDIR}) -else() - # the Dune 2.5 way of calling these macros - dune_add_latex_document(0_dumux-handbook.tex - BIBFILES dumux-handbook.bib - INPUTS ${TEX_INPUTS} - IMAGES ${TEX_IMAGES}) +dune_add_latex_document(0_dumux-handbook.tex + BIBFILES dumux-handbook.bib + INPUTS ${TEX_INPUTS} + IMAGES ${TEX_IMAGES}) - create_doc_install(${CMAKE_CURRENT_BINARY_DIR}/0_dumux-handbook.pdf - ${CMAKE_INSTALL_DOCDIR} 0_dumux-handbook) +create_doc_install(${CMAKE_CURRENT_BINARY_DIR}/0_dumux-handbook.pdf + ${CMAKE_INSTALL_DOCDIR} 0_dumux-handbook) endif() diff --git a/doc/handbook/dumux-handbook.bib b/doc/handbook/dumux-handbook.bib index 97600f24dfb490c06031aaf4ea2f4f973edd4f45..761858624ec14e9035a8d2d379427a51d74f6f5a 100644 --- a/doc/handbook/dumux-handbook.bib +++ b/doc/handbook/dumux-handbook.bib @@ -135,7 +135,8 @@ volume = {15}, number = {03}, pages = {658--669}, - publisher = {Society of Petroleum Engineers} + publisher = {Society of Petroleum Engineers}, + url = {https://dx.doi.org/10.2118/106435-PA} } @@ -201,7 +202,8 @@ volume = {42}, number = {2-3}, pages = {296--305}, - publisher = {Springer} + publisher = {Springer}, + url = {https://doi.org/10.1007/s00254-001-0499-2} } @ARTICLE{BELIAEV2001, @@ -431,11 +433,11 @@ journal = {Journal of Contaminant Hydrology}, year = {2005} } -@phdthesis{nuske2009, +@MastersThesis{nuske2009, title={{Determination of interfacial area-capillary pressure-saturation relationships for a single fracture}}, author={Nuske, K. P.}, year={2009}, - school={Master’s thesis, Universit{\"a}t Stuttgart} + school={Universit{\"a}t Stuttgart} } @article{ferrell1967, @@ -462,6 +464,29 @@ url={https://dx.doi.org/10.1021/jp021943g} } +@article{witherspoon1965, +author = {Witherspoon, P. A. and Saraf, D. N.}, +title = {{Diffusion of Methane, Ethane, Propane, and n-Butane in Water from 25 to 43°}}, +journal = {The Journal of Physical Chemistry}, +volume = {69}, +number = {11}, +pages = {3752--3755}, +year = {1965}, +doi = {10.1021/j100895a017}, +url = {https://doi.org/10.1021/j100895a017}, +} + +@article{han2003, + title={{Description of fluid flow around a wellbore with stress-dependent porosity and permeability}}, + author={Han, Gang and Dusseault, Maurice B}, + journal={Journal of Petroleum science and engineering}, + volume={40}, + number={1-2}, + pages={1--16}, + year={2003}, + publisher={Elsevier} +} + @INPROCEEDINGS{A3:aavatsmark:1994, author = {Aavatsmark, I. and Barkve, T. and B{\o}e, {\O}. and Mannseth, T.}, title = {{Discretization on non-orthogonal, curvilinear grids for multiphase @@ -557,7 +582,8 @@ title = {{Fifth Comparative Solution Project: Evaluation of Miscible Flood Simulators}}, journal = {Society of Petroleum Engineers}, year = {1987}, - volume = {SPE 16000} + volume = {SPE 16000}, + url = {https://doi.org/10.2118/16000-MS} } @ARTICLE{WHITAKER1985, @@ -956,7 +982,8 @@ journal = {Advances in Water Resources}, year = {2002}, volume = {25}, - pages = {551--564} + pages = {551--564}, + url = {https://doi.org/10.1016/S0309-1708(02)00015-5} } @BOOK{MEISTER2008, @@ -1064,7 +1091,7 @@ url = {http://www.sciencedirect.com/science/article/pii/S0169772204001160} volume = {198}, pages = {71--78} } -@misc{cooper2008, +@misc{cooper2008, title={{Release of the IAPWS formulation 2008 for the viscosity of ordinary water substance}}, author={Cooper, J. R. and Dooley, R. B.}, year={2008}, @@ -1373,12 +1400,11 @@ url={http://dx.doi.org/10.1007/s11242-015-0599-1} url={http://oai.dtic.mil/oai/oai?verb=getRecord&metadataPrefix=html&identifier=ADA044002} } -@phdthesis{ebigbo2005, +@MastersThesis{ebigbo2005, title={{Thermal effects of carbon dioxide sequestration in the subsurface}}, author={Ebigbo, A.}, year={2005}, - school={Master’s thesis, Institut f{\"u}r Wasserbau, Universit{\"a}t Stuttgart}, - url={https://www.hydrosys.uni-stuttgart.de/institut/hydrosys/publikationen/paper/Dipl_Anozie_Ebigbo.pdf} + school={Institut f{\"u}r Wasserbau, Universit{\"a}t Stuttgart}, } @article{michaelides1981, @@ -1422,7 +1448,8 @@ url={http://dx.doi.org/10.1007/s11242-015-0599-1} year = {1998}, volume = {36}, pages = {401--422}, - number = {3} + number = {3}, + url = {http://dx.doi.org/10.1029/98RG00878} } @article{ward1964, @@ -1445,7 +1472,8 @@ url={http://dx.doi.org/10.1007/s11242-015-0599-1} author = {Bastian, P. and Birken, K. and Lang, S. and Johannsen, K. and Neuss, N. and Rentz-Reichert, H. and Wieners, C.}, volume = {1}, - series = {Computing and Visualization in Science} + series = {Computing and Visualization in Science}, + url = {https://doi.org/10.1007/s007910050003} } @MASTERSTHESIS{A3:grass:2005, @@ -1571,3 +1599,250 @@ url={http://dx.doi.org/10.1007/s11242-015-0599-1} timestamp = {2017.05.11}, url = {http://dx.doi.org/10.1023/B:IJOT.0000022327.04529.f3} } + +@Article{Laufer1954a, + author = {John Laufer}, + title = {{The structure of turbulence in fully developed pipe flow}}, + journal = {NACA Report}, + year = {1954}, + volume = {1174}, + pages = {417--434}, + owner = {fetzer}, + timestamp = {2012.09.03}, + url = {https://ntrs.nasa.gov/search.jsp?R=19930092199} +} + +@Article{Hanna1981a, + author = {O. T. Hanna and O. C. Sandell and P. R. Mazet}, + title = {{Heat and Mass Transfer in Turbulent Flow Under Conditions of Drag Reduction}}, + journal = {AIChE Journal}, + year = {1981}, + volume = {27}, + number = {4}, + pages = {693--697}, + doi = {10.1002/aic.690270424}, + url = {http://dx.doi.org/10.1002/aic.690270424} +} + +@Book{Oertel2012a, + title = {{Prandtl - F\"uhrer durch die Str\"omungslehre: Grundlagen und Ph\"anomene}}, + publisher = {Springer Vieweg}, + year = {2012}, + author = {Oertel, Herbert}, + isbn = {978-3-8348-2315.1}, + pages = {XII, 764}, + address = {Wiesbaden}, + edition = {13}, + editor = {Oertel, Herbert and Böhle, Martin}, + doi = {10.1007/978-3-8348-2315-1}, + url = {http://dx.doi.org/10.1007/978-3-8348-2315-1} +} + +@Article{vanDriest1956a, + author = {E. R. {van Driest}}, + title = {{On Turbulent Flow Near a Wall}}, + journal = {AIAA Journal}, + year = {1956}, + volume = {23}, + number = {11}, + pages = {1007--1011}, + doi = {10.2514/8.3713}, + url = {http://dx.doi.org/10.2514/8.3713} +} + +@Article{Baldwin1978a, + author = {B. S. Baldwin and H. Lomax}, + title = {{Thin Layer Approximation and Algebraic Model for Seperated Turbulent Flows}}, + journal = {ACM Trans Math Software}, + year = {1978}, + volume = {78--257}, + pages = {1--9}, + doi = {10.2514/6.1978-257}, + url = {http://dx.doi.org/10.2514/6.1978-257} +} + +@Article{Patel1985a, + author = {Patel, V. C. and Rodi, W. and Scheuerer, G.}, + title = {{Turbulence models for near-wall and low Reynolds number flows - A review}}, + journal = {AIAA Journal}, + year = {1985}, + volume = {23}, + pages = {1308--1319}, + number = {9}, + doi = {10.2514/3.9086}, + url = {http://dx.doi.org/10.2514/3.9086}, +} + +@Article{Chien1982a, + author = {Chien, Kuei-Yuan}, + title = {{Predictions of Channel and Boundary-Layer Flows with a Low-Reynolds-Number Turbulence Model}}, + journal = {AIAA Journal}, + year = {1982}, + volume = {20}, + pages = {33--38}, + number = {1}, + booktitle = {AIAA Journal}, + doi = {10.2514/3.51043}, + issn = {0001-1452}, + publisher = {American Institute of Aeronautics and Astronautics}, + url = {http://dx.doi.org/10.2514/3.51043}, +} + +@Article{Lam1981a, + author = {Lam, C. K. G. and Bremhorst, K. A}, + title = {{Modified Form of the k-\varepsilon-Model for Predicting Wall Turbulence}}, + journal = {Journal of Fluids Engineering}, + year = {1981}, + volume = {103}, + number = {3}, + pages = {456--460}, + doi = {10.1115/1.3240815}, + url = {http://dx.doi.org/10.1115/1.3240815}, +} + +@Article{flekkoy1995a, + title={{Hydrodynamic dispersion at stagnation points: Simulations and experiments}}, + author={{Flekk{\o}y, EG and Oxaal, U and Feder, J and J{\o}ssang, T}}, + journal={Physical Review E}, + volume={52}, + number={5}, + pages={4952}, + year={1995}, + publisher={APS}, + doi = {10.1103/PhysRevE.52.4952}, + url = {https://doi.org/10.1103/PhysRevE.52.4952} +} + +@Article{venturoli2006a, + title={{Two-dimensional lattice-Boltzmann simulations of single phase flow in a pseudo two-dimensional micromodel}}, + author={{Venturoli, Maddalena and Boek, Edo S}}, + journal={Physica A: Statistical Mechanics and its Applications}, + volume={362}, + number={1}, + pages={23--29}, + year={2006}, + publisher={Elsevier}, + doi = {10.1016/j.physa.2005.09.006}, + url = {https://doi.org/10.1016/j.physa.2005.09.006} + } + +@Article{Wilcox2008a, + author = {David C. Wilcox}, + title = {{Formulation of the $k$-$\omega$ Turbulence Model Revisited}}, + journal = {AIAA Journal}, + year = {2008}, + volume = {46}, + pages = {2823--2838}, + number = {11}, + doi = {10.2514/1.36541}, + url = {https://doi.org/10.2514/1.36541} +} + +@Article{launder1974a, +author = {B.E. Launder and B.I. Sharma}, +title = {{Application of the energy-dissipation model of turbulence to the calculation of flow near a spinning disc}}, +journal = {Letters in Heat and Mass Transfer}, +volume = {1}, +number = {2}, +pages = {131 -- 137}, +year = {1974}, +issn = {0094--4548}, +doi = {https://doi.org/10.1016/0094-4548(74)90150-7}, +url = {http://www.sciencedirect.com/science/article/pii/0094454874901507}, +} + +@Book{Versteeg2009a, + title = {{An Introduction to Computational Fluid Dynamics}}, + publisher = {Pearson Education}, + year = {2009}, + author = {Versteeg, Henk and Malalasekra, Weeratunge}, + isbn = {978-0-13-127498-3}, + pages = {XII, 503}, + address = {Harlow}, + edition = {2}, +} + +@InCollection{Spalart1992a, + author = {Spalart, P. R. and Allmaras, S. R.}, + title = {{A one-equation turbulence model for aerodynamic flows}}, + booktitle = {Aerospace Sciences Meetings}, + publisher = {American Institute of Aeronautics and Astronautics}, + year = {1992}, + pages = {--}, + doi = {10.2514/6.1992-439}, + url = {http://dx.doi.org/10.2514/6.1992-439} +} + +@book{Donea2003, + title={Finite element methods for flow problems}, + author={Donea, Jean and Huerta, Antonio}, + year={2003}, + publisher={John Wiley \& Sons} +} + +@inproceedings{Angeli2017, + title={FVCA8 Benchmark for the Stokes and Navier--Stokes Equations with the TrioCFD Code—Benchmark Session}, + author={Angeli, P-E and Puscas, M-A and Fauchet, G and Cartalade, A}, + booktitle={International Conference on Finite Volumes for Complex Applications}, + pages={181--202}, + year={2017}, + organization={Springer} +} + +@InProceedings{Kovasznay1948, + author = {Kovasznay, L. I. G.}, + title = {Laminar flow behind a two-dimensional grid}, + booktitle = {Mathematical Proceedings of the Cambridge Philosophical Society}, + year = {1948}, + volume = {44}, + pages = {58--62}, + organization = {Cambridge Univ Press}, +} + +@PHDTHESIS{Class2001, + author = {H. Class}, + title = {{Theorie und numerische Modellierung nichtisothermer Mehrphasenprozesse in NAPL-kontaminierten por"osen Medien}}, + school = {Universit\"at Stuttgart}, + year = {2001} +} + +@Article{Shi2011, +author={Shi, J. X. and Wang, J. H.}, +title={A Numerical Investigation of Transpiration Cooling with Liquid Coolant Phase Change}, +journal={Transport in Porous Media}, +year={2011}, +volume={87}, +number={3}, +pages={703--716}, +doi={10.1007/s11242-010-9710-9}, +url={https://doi.org/10.1007/s11242-010-9710-9} +} + +@article{nagel2014, +title={The influence of gas--solid reaction kinetics in models of thermochemical heat storage under monotonic and cyclic loading}, +author={Nagel, T and Shao, H and Ro{\ss}kopf, C and Linder, M and W{\"o}rner, A and Kolditz, O}, +journal={Applied Energy}, +volume={136}, +pages={289--302}, +year={2014}, +publisher={Elsevier} +} + +@article{shao2013, +title={{Non-equilibrium thermo-chemical heat storage in porous media: Part 2--A 1D computational model for a calcium hydroxide reaction system}}, +author={Shao, H and Nagel, T and Ro{\ss}kopf, C and Linder, M and W{\"o}rner, A and Kolditz, O}, +journal={Energy}, +volume={60}, +pages={271--282}, +year={2013}, +publisher={Elsevier} +} + +@article{Binning1999, +title={Practical implementation of the fractional flow approach to multi-phase flow simulation}, +author={P. Binning and M. A. Celia}, +journal={Advances in water resources}, +volume={22}, +pages={461-478}, +year={1999} +} diff --git a/doc/handbook/installDumux.sh b/doc/handbook/installDumux.sh index bca2ab4612c51921a4048f3826fbda70edb282f2..60295e5089cdf053438b69d0578a55c9b8df123f 100644 --- a/doc/handbook/installDumux.sh +++ b/doc/handbook/installDumux.sh @@ -10,25 +10,11 @@ Make sure to be connected to the internet." echo "*************************************************" # the core modules for MOD in common geometry grid localfunctions istl; do - if [ ! -d "dune-$MOD" ]; then - git clone -b releases/2.5 https://gitlab.dune-project.org/core/dune-$MOD.git - else - echo "Skip cloning dune-$MOD because the folder already exists." - cd dune-$MOD - git checkout releases/2.5 - cd .. - fi + git clone -b releases/2.6 https://gitlab.dune-project.org/core/dune-$MOD.git done # dumux -if [ ! -d "dumux" ]; then - git clone -b 3.0.0-alpha https://git.iws.uni-stuttgart.de/dumux-repositories/dumux.git -else - echo "Skip cloning dumux because the folder already exists." - cd dumux - git checkout 3.0.0-alpha - cd .. -fi +git clone -b releases/3.0 https://git.iws.uni-stuttgart.de/dumux-repositories/dumux.git if [ $? -ne 0 ]; then echo "*************************************************" @@ -42,7 +28,7 @@ echo "(2/2) Configure dune modules and dumux. Build the dune libaries. This may take several minutes." echo "*************************************************" # run build -./dune-common/bin/dunecontrol --opts=dumux/myoptim.opts all +./dune-common/bin/dunecontrol --opts=dumux/cmake.opts all # if [ $? -ne 0 ]; then echo "*************************************************" diff --git a/doc/handbook/PNG/box_disc.png b/doc/handbook/png/box_disc.png similarity index 100% rename from doc/handbook/PNG/box_disc.png rename to doc/handbook/png/box_disc.png diff --git a/doc/handbook/PNG/cc_disc.png b/doc/handbook/png/cc_disc.png similarity index 100% rename from doc/handbook/PNG/cc_disc.png rename to doc/handbook/png/cc_disc.png diff --git a/doc/handbook/png/cctpfa.png b/doc/handbook/png/cctpfa.png new file mode 100644 index 0000000000000000000000000000000000000000..ef61ef9cba8a11c77cda9f2fa847b91c5a26f12e Binary files /dev/null and b/doc/handbook/png/cctpfa.png differ diff --git a/doc/handbook/png/dalton1.png b/doc/handbook/png/dalton1.png new file mode 100644 index 0000000000000000000000000000000000000000..b681e597953cffe3cae320f8d029188c5e187cab Binary files /dev/null and b/doc/handbook/png/dalton1.png differ diff --git a/doc/handbook/png/dalton2.png b/doc/handbook/png/dalton2.png new file mode 100644 index 0000000000000000000000000000000000000000..be04f04bfad603d43b39830d4174b3cc3749f913 Binary files /dev/null and b/doc/handbook/png/dalton2.png differ diff --git a/doc/handbook/PNG/dumux_strucutre_flowchart_horizontal_explained.png b/doc/handbook/png/dumux_strucutre_flowchart_horizontal_explained.png similarity index 100% rename from doc/handbook/PNG/dumux_strucutre_flowchart_horizontal_explained.png rename to doc/handbook/png/dumux_strucutre_flowchart_horizontal_explained.png diff --git a/doc/handbook/PNG/dunedesign.png b/doc/handbook/png/dunedesign.png similarity index 100% rename from doc/handbook/PNG/dunedesign.png rename to doc/handbook/png/dunedesign.png diff --git a/doc/handbook/SVG/box_disc.svg b/doc/handbook/svg/box_disc.svg similarity index 100% rename from doc/handbook/SVG/box_disc.svg rename to doc/handbook/svg/box_disc.svg diff --git a/doc/handbook/SVG/cc_disc.svg b/doc/handbook/svg/cc_disc.svg similarity index 100% rename from doc/handbook/SVG/cc_disc.svg rename to doc/handbook/svg/cc_disc.svg diff --git a/doc/handbook/svg/cctpfa.svg b/doc/handbook/svg/cctpfa.svg new file mode 100644 index 0000000000000000000000000000000000000000..490ab0a792c6faf5e8f196c3df9696449fb35c7d --- /dev/null +++ b/doc/handbook/svg/cctpfa.svg @@ -0,0 +1,800 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/doc/handbook/svg/dalton1.svg b/doc/handbook/svg/dalton1.svg new file mode 100644 index 0000000000000000000000000000000000000000..37fdb4272b41f26e54868779b6f2b01a7494d8a7 --- /dev/null +++ b/doc/handbook/svg/dalton1.svg @@ -0,0 +1,432 @@ + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/doc/handbook/svg/dalton2.svg b/doc/handbook/svg/dalton2.svg new file mode 100644 index 0000000000000000000000000000000000000000..f25a016daec9e9868d9559949ddde31e9b117973 --- /dev/null +++ b/doc/handbook/svg/dalton2.svg @@ -0,0 +1,432 @@ + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/doc/handbook/svg/mpfa_iv.svg b/doc/handbook/svg/mpfa_iv.svg new file mode 100644 index 0000000000000000000000000000000000000000..5642e339cdb545b4a545efc3cea73f21c3886c51 --- /dev/null +++ b/doc/handbook/svg/mpfa_iv.svg @@ -0,0 +1,2764 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/doc/handbook/svg/staggered_grid.svg b/doc/handbook/svg/staggered_grid.svg new file mode 100644 index 0000000000000000000000000000000000000000..fce64bce78441c35e199bd708ad4fb3d8b6d9f40 --- /dev/null +++ b/doc/handbook/svg/staggered_grid.svg @@ -0,0 +1,4525 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +