README.md 7.77 KB
Newer Older
1
<img src="doc/logo/dumux_logo_hires_whitebg.png" alt="dumux logo" width="400"/>
2

3
What is DuMu<sup>x</sup>?
4
===============
5

6
7
[DuMu<sup>x</sup>][0] is a simulation toolbox mainly aimed at flow and transport
processes in porous media. DuMu<sup>x</sup> is based on the [DUNE][1]
8
9
10
framework and aims to provide a multitude of numerical models as well
as flexible discretization methods for complex non-linear phenomena,
such as CO2 sequestration, soil remediation, drug delivery in cancer
11
12
therapy and more. Have a look at our publications
(see below: [How to cite](#how-to-cite))
13
for a more detailed description of the goals and motivations behind DuMu<sup>x</sup>.
14
15
16


Installation
17
===============
18

19
Have a look at the [installation guide][3] or use the [DuMu<sup>x</sup> handbook][4],
Timo Koch's avatar
Timo Koch committed
20
Chapter 2.
21

Timo Koch's avatar
Timo Koch committed
22
23
24
Documentation
==============

25
The following resources are useful to get started with DuMu<sup>x</sup>:
Timo Koch's avatar
Timo Koch committed
26

27
* [Getting started guide](https://dumux.org/gettingstarted/) on the [DuMu<sup>x</sup> website](https://dumux.org/)
28
29
* [Handbook](https://dumux.org/handbook), a detailed DuMu<sup>x</sup> manual,
* [DuMu<sup>x</sup> course materials](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux-course/tree/master),
30
* [Examples](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/tree/master/examples), with detailed description of code and results,
31
* [Class documentation](https://dumux.org/docs/doxygen/master/) generated from the source code,
Timo Koch's avatar
Timo Koch committed
32
33
34
35
* [Mailing list](https://listserv.uni-stuttgart.de/mailman/listinfo/dumux),
* [Changelog](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/blob/master/CHANGELOG.md), where all changes between different release versions are listed and explained.

Some helpful code snippets are available in the [Wiki](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/wikis/home).
36
37

License
38
========
39

40
DuMu<sup>x</sup> is licensed under the terms and conditions of the GNU General
41
Public License (GPL) version 3 or - at your option - any later
42
version. The GPL can be [read online][5] or in the [LICENSE.md](LICENSE.md) file
43
provided in the topmost directory of the DuMu<sup>x</sup> source code tree.
44

45
Please note that DuMu<sup>x</sup>' license, unlike DUNE's, does *not* feature a
46
template exception to the GNU General Public License. This means that
47
you must publish any source code which uses any of the DuMu<sup>x</sup> header
48
49
50
51
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.

52
See the file [LICENSE.md](LICENSE.md) for full copying permissions.
53

54
55
56
How to cite
============

57
58
DuMu<sup>x</sup> is research software and developed at research institutions.
If you are using DuMu<sup>x</sup> in scientific publications and in
59
60
61
62
63
64
65
the academic context, please cite (at least one)
of our publications:

* [Koch, T., Gläser, D., Weishaupt, K., Ackermann, S., Beck, M., Becker, B.,
  Burbulla, S., Class, H., Coltman, E., Emmert, S., Fetzer, T., Grüninger, C.,
  Heck, K., Hommel, J., Kurz, T., Lipp, M., Mohammadi, F., Scherrer, S.,
  Schneider, M., Seitz, G., Stadler, L., Utz, M., Weinhardt, F.
66
  & Flemisch, B. (_2020_). __DuMu<sup>x</sup> 3 – an open-source simulator for solving flow
67
68
69
70
71
72
  and transport problems in porous media with a focus on model coupling.__
  _Computers & Mathematics with Applications_,
  https://doi.org/10.1016/j.camwa.2020.02.012][7]

* [Flemisch, B., Darcis, M., Erbertseder, K., Faigle, B., Lauser, A.,
  Mosthaf, K., Müthing, S., Nuske, P., Tatomir, A., Wolff, M.,
73
  & Helmig, R. (_2011_). __DuMu<sup>x</sup>: DUNE for multi-{phase,component,scale,physics,…}
74
75
76
77
78
79
80
81
82
  flow and transport in porous media__.
  _Advances in Water Resources_, 34(9), 1102–1112.
  https://doi.org/10.1016/j.advwatres.2011.03.007][2]

You can also cite specific releases published on Zenodo:
[![zenodo badge](https://zenodo.org/badge/DOI/10.5281/zenodo.2479594.svg)](https://doi.org/10.5281/zenodo.2479594)



Timo Koch's avatar
Timo Koch committed
83
Automated Testing
84
==================
Timo Koch's avatar
Timo Koch committed
85

86
87
88
* DuMu<sup>x</sup> 3.2 / Dune 2.7: [![buildbot badge](https://git.iws.uni-stuttgart.de/buildbot/badges/dumux-rel-3-2-dune-rel-2-7-clang-full.svg)](https://git.iws.uni-stuttgart.de/buildbot/#/builders)
* DuMu<sup>x</sup> master / Dune 2.7: [![buildbot badge](https://git.iws.uni-stuttgart.de/buildbot/badges/dumux-master-dune-rel-2-7-clang-full.svg)](https://git.iws.uni-stuttgart.de/buildbot/#/builders)
* DuMu<sup>x</sup> master / Dune master: [![buildbot badge](https://git.iws.uni-stuttgart.de/buildbot/badges/dumux-master-dune-master-clang-full.svg)](https://git.iws.uni-stuttgart.de/buildbot/#/builders)
Timo Koch's avatar
Timo Koch committed
89

90
DuMu<sup>x</sup> features many tests (some unit tests and test problems) that can
Timo Koch's avatar
Timo Koch committed
91
be run manually. We have experimental support for automated testing with buildbot.
92
Click <a href="https://git.iws.uni-stuttgart.de/buildbot/#/builders" target="_blank">here (buildbot)</a>
Timo Koch's avatar
Timo Koch committed
93
94
95
to see the latest builds (clicking on a build
number will show a detailed overview of the build).

Timo Koch's avatar
Timo Koch committed
96
[![coverage report](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux-coverage/badges/master/coverage.svg)](https://pages.iws.uni-stuttgart.de/dumux-repositories/dumux-coverage/)
Timo Koch's avatar
Timo Koch committed
97
98
99
100
101
102

A weekly coverage report of the test suite is created by gcovr/gcov. The report
currently doesn't include non-instantiated code, so the real coverage is likely lower. However,
only a few lines of code are never instatiated in the comprehensive test suite.


103
104
105
106
107
108
109
110
111
Contributing
=============

Contributions are highly welcome. Please ask questions over the [mailing list](mailto:dumux@listserv.uni-stuttgart.de).
Please review the [contribution guidelines](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/blob/master/CONTRIBUTING.md)
before opening issues and merge requests. For bug reports contact us
over the mailing list, or file an [issue](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/issues). For bug fixes,
feature implementations open a [merge request](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/merge_requests)
or send us formatted patches.
Timo Koch's avatar
Timo Koch committed
112

113
114
115
116
117
118
Backwards Compatibility
=======================

For a detailed description of the backwards compatibility policy, 
please see [contribution guidelines](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/blob/master/CONTRIBUTING.md).

119
DuMu<sup>x</sup> releases are split into major(e.g. 2.0, 3.0) and minor (e.g. 3.1, 3.2, 3.3) releases. 
120
121
122
123
124
125
126
127
128
Major releases are not required to maintain backwards compatibility (see below), 
but would provide a detailed guide on how to update dependent modules. 
For each minor release, maintaining backwards compatibility is strongly encouraged and recommended.

Despite the goal of maintaining backwards compatibility across minor releases,
for more complicated changes, this is decided upon on a case to case basis, due to limited developer resources. 
In the case that implementing full backwards compatibility for an update is not feasible, or would require unreasonable resources, 
the degree of backwards compatibility be decided by a vote in one of the monthly core developer meetings.

129
130
131
Major version update, 2.12 to 3.0
===================================

132
With the version update to version 3, many features have been added and a lot has been improved in DuMu<sup>x</sup>. See the
133
134
[changelog](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/blob/master/CHANGELOG.md) for a list of changes.
If you decide to update from version 2.12, please have a look at our small
Ned Coltman's avatar
Ned Coltman committed
135
[guide](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/-/wikis/Hints/Upgrade-to-Dumux-3)
136
137
on how to update an application to the new version.

138
139
140
141
142
143
[0]: https://dumux.org
[1]: https://dune-project.org/
[2]: https://dumux.org/documents/dumux_awrpaper.pdf
[3]: https://dumux.org/installation
[4]: https://dumux.org/documents/dumux-handbook-master.pdf
[5]: https://www.gnu.org/licenses/gpl-3.0.en.html
Ned Coltman's avatar
Ned Coltman committed
144
[6]: https://www.iws.uni-stuttgart.de/en/lh2/
145
[7]: https://doi.org/10.1016/j.camwa.2020.02.012