Merge branch 'feature/improve-description' into 'master'

[README] improve section on Dumux coupling

See merge request DennisGlaeser/frackit!53

README.md

@@ -10,7 +10,7 @@ Frackit is an open-source framework for the stochastic generation of fracture ne
 The implementation is written in C++ language and extensively uses
 [OpenCascade][2], an open-source Computer Aided Design (CAD) library.
 
-The geometries generated by Frackit can be exported into a number of standard CAD
+The geometric data generated by Frackit can be exported into a number of standard CAD
 file formats supported by [OpenCascade][2]. This allows for visualization with a
 variety of tools, as for example the [CAD Assistant][3] developed by [OpenCascade][2],
 or [Gmsh][1], a three-dimensional finite element mesh generator.
@@ -18,17 +18,26 @@ or [Gmsh][1], a three-dimensional finite element mesh generator.
 Coupling to [DuMuX][0]
 ======================
 
-Frackit also features output routines to [Gmsh][1] file format (.geo), where mesh
-size specifications can be defined upon fracture network generation. This allows
-for the generation of computational meshes using [Gmsh][1], which are supported
-by the open-source simulator [DuMuX][0] for flow and transport in porous media.
-The .geo files produced by Frackit lead to three-dimensional meshes that are aligned
-with the fracture geometries such that the element faces coincide with the fractures,
-which can be directly plugged into the [DuMuX][0] module for discrete fracture-matrix
-simulations of single- and two-phase flow (see e.g. https://arxiv.org/pdf/1909.05052.pdf).
-
-For example, the pressure distribution on the fractures and the fluid velocities
-in the domain, for the fracture network shown above, could look like this:
+Frackit features output routines to [Gmsh][1] file format (.geo), where in addition
+to the geometric data, mesh size specifications can be defined upon fracture network
+generation. This allows for the generation of computational meshes using [Gmsh][1],
+which are supported, among other simulators, by the open-source simulator [DuMuX][0]
+for flow and transport in porous media. The .geo files produced by Frackit, when
+meshed with [Gmsh][1], lead to mesh files that contain the three-dimensional elements
+that discretize the domain, two-dimensional elements that discretize the fractures,
+and one-dimensional elements that discretize the intersections of fractures. The
+meshes are conforming in the sense that higher-dimensional elements follow the
+lower-dimensional features by aligning the element faces with the lower-dimensional
+geometries.
+
+This type of mesh format is supported by the [DuMuX][0] module for discrete
+fracture-matrix simulations of single- and two-phase flow
+(see e.g. <cite>Koch et al. (2019)</cite>, <cite>Gläser et al. (2019)</cite>, <cite>Gläser et al (2017)</cite>). Thus, you can use Frackit in a toolchain with [Gmsh][1] and
+[DuMuX][0] to perform simulations on the generated fracture networks.
+
+The following picture shows an exemplary result for a single-phase simulation
+on the fracture network shown above, and it depicts the pressure distribution
+on the fractures as well as the fluid velocities in the domain:
 
 <p align="center">
     <img src="doc/img/pressuresolution.png" alt="dumux frackit example" width="800"/>
@@ -62,17 +71,18 @@ After the desired number of fracture entities have been generated, an __EntityNe
 can be constructed from the raw entities. This intersects and fragments all entities, and
 if desired, one can confine the network to a domain of choice.
 
-Note that none of these steps are not mandatory, nor do they occur in a fixed order.
-Instead, users are motivated to implement their own applications using the provided
-functions, classes and concepts. The modular design of the above-mentioned building
-blocks enables users to fully customize each step to their needs. Three exemplary
-applications are contained in this repository:
+Note that none of these steps are mandatory and there is no fixed and prescribed
+program flow. Instead, users are motivated to implement their own applications
+using the provided functions, classes and concepts. The modular design of the
+above-mentioned building blocks enables users to fully customize each step to
+their needs. Three exemplary applications are contained in this repository:
 
 * [Example 1][5] Generation of a simple network consisting of quadrilaterals with two main orientations.
 * [Example 2][6] Generation of a network of quadrilaterals embedded in a cylindrical domain (mimicking a core sample).
 * [Example 3][4] Generation of a network consisting of both disks and quadrilaterals, confined and contained in one layer of a domain that is composed of three layers.
 
 
+
 Documentation
 =============
 
@@ -204,7 +214,7 @@ before merging.
 * If you have developer status you don't need to do a fork and you can create branches directly.
 
 In this project, we follow the [styleguide][2] of the [DuMuX][0] project.
-Please have a look at these before you start coding your contributions.
+Please have a look at this before you start coding your contributions.
 
 
 Ongoing Developments
@@ -214,6 +224,22 @@ Ongoing Developments
 * Capabilities for translation of fracture networks into graphs, allowing for efficient characterization of the network based on its graph representation.
 * Python bindings
 
+References
+====================
+
+Koch, T., Gläser, D., Weishaupt, K., Ackermann, S., Beck, M., Becker, B., Flemisch, B. et al. (2019).<br>
+_DuMuX 3 -- an open-source simulator for solving flow and transport problems in porous media with a focus
+on model coupling._<br>
+ArXiv E-Prints, 1909, arXiv:1909.05052
+
+Gläser, D., Flemisch, B., Helmig, R., Class, H. (2019).<br>
+_A hybrid-dimensional discrete fracture model for non-isothermal two-phase flow in fractured porous media._<br>
+GEM - International Journal on Geomathematics, 10(1), 5.
+
+Gläser, D., Helmig, R., Flemisch, B., Class, H. (2017).<br>
+_A discrete fracture model for two-phase flow in fractured porous media._<br>
+Advances in Water Resources, 110. doi:10.1016/j.advwatres.2017.10.031
+
 [0]: https://dumux.org
 [1]: http://gmsh.info/
 [2]: https://www.opencascade.com/content/download-center