README.md 11.8 KB
Newer Older
1
2
<!--- Example picture --->
<p align="center">
Dennis Gläser's avatar
Dennis Gläser committed
3
    <img src="doc/img/titlepicture.png" alt="frackit example" width="800"/>
4
</p>
Dennis Gläser's avatar
Dennis Gläser committed
5

6
7
8
9
10
What is Frackit?
================

Frackit is an open-source framework for the stochastic generation of fracture networks.
The implementation is written in C++ language and extensively uses
11
[OpenCASCADE][2], an open-source Computer Aided Design (CAD) library.
12

13
The geometric data generated by Frackit can be exported into a number of standard CAD
14
15
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],
16
17
18
19
20
or [Gmsh][1], a three-dimensional finite element mesh generator.

Coupling to [DuMuX][0]
======================

21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
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:
41
42
43
44
45
46
47

<p align="center">
    <img src="doc/img/pressuresolution.png" alt="dumux frackit example" width="800"/>
</p>

The source code to this example, including installation instructions, can be found
[here][13].
48
49
50
51

General Concept
===============

Dennis Gläser's avatar
Dennis Gläser committed
52
### Geometry Sampling
53
The generation of the fracture networks occurs by randomly sampling instances of the
54
desired fracture geometry on the basis of probability distributions, which
55
56
57
can be defined by the user. The implementation allows for both selecting the type of
distribution (uniform, exponential, etc.) as well as the distribution parameters.

Dennis Gläser's avatar
Dennis Gläser committed
58
### Constraints Evaluation
Dennis Gläser's avatar
Dennis Gläser committed
59
After the generation of a new candidate for a fracture entity, a number of constraints can
60
61
62
63
64
65
66
67
68
be evaluated for it. These can be used to enforce topological characteristics of the
fracture network, e.g. fracture spacing, by defining a minimum distance between entities.
Other constraints are targeted mainly at guaranteeing certain mesh properties by avoiding
very small length scales, and thus, small elements in the computational mesh. As constraints
one can define a minimum length scale of the intersections between fracture entities, a
minimum intersection angle, and a minimum distance of the intersection geometry to the boundary
of the intersecting entities. If the user-defined constraints are not fulfilled, the candidate
is rejected.

Dennis Gläser's avatar
Dennis Gläser committed
69
### Fragmentation of the network
70
71
72
73
After the desired number of fracture entities have been generated, an __EntityNetwork__
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.

74
75
76
77
78
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:
79
80

* [Example 1][5] Generation of a simple network consisting of quadrilaterals with two main orientations.
Dennis Gläser's avatar
Dennis Gläser committed
81
82
* [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.
83
84


85

86
87
88
Documentation
=============

Dennis Gläser's avatar
Dennis Gläser committed
89
90
A class documentation can be generated from the source code using
[Doxygen][8] (see Installation notes).
91
Moreover, the [Examples][7] contained in this repository provide a good overview over
Dennis Gläser's avatar
Dennis Gläser committed
92
93
the capabilities of Frackit and can serve as a starting point to develop your own
application.
94
95
96
97
98


Installation
============

Dennis Gläser's avatar
Dennis Gläser committed
99
100
Please note that the following requirements need to be installed:

101
* OpenCASCADE (>= 7.3.0) (Note: Testing occurs with 7.3.0, no guarantee to work with higher versions)
Dennis Gläser's avatar
Dennis Gläser committed
102
* CMake (>3.0)
Dennis Gläser's avatar
Dennis Gläser committed
103
104
105
* C, C++ compiler (C++17 required)
* Optional: Doxygen (>= 1.8)

106
107
### Installation of OpenCASCADE
Frackit requires parts of the [OpenCASCADE][2] library to be installed on your system.
108
Thanks to the ["FreeCAD maintainers" team][15], there are Debian packages of
109
[OpenCASCADE][2] available (see [this link][14]). To install the required packages,
110
111
112
113
114
115
116
117
118
119
120
121
122
you have to add the repository by typing

```sh
sudo add-apt-repository ppa:freecad-maintainers/occt-releases
sudo apt-get update
```

into the terminal. Then, you can install the packages with

```sh
sudo apt-get install libocct-modeling-algorithms-7.3 libocct-modeling-algorithms-dev libocct-foundation-7.3 libocct-foundation-dev libocct-modeling-data-7.3 libocct-modeling-data-dev
```

123
If you prefer building [OpenCASCADE][2] from the sources, you can download the
124
125
126
127
128
source code [HERE][2] after registration. For the version 7.3 release, you can
click [this link][16] to download the tarball without registration.
<!-- EDIT: PUBLIC ACCESS TO THE DEVELOPMENT PORTAL HAS BEEN STOPPED, MAYBE PUT
THE FOLLOWING PHRASE BACK IN IF THEY RE-OPEN IT!
, or get the tarballs from their
Dennis Gläser's avatar
Dennis Gläser committed
129
development portal at http://dev.opencascade.org. Click [this link][16] to download
130
131
the tarball for the version 7.3 release. -->
Details on building [OpenCASCADE][2]
Dennis Gläser's avatar
Dennis Gläser committed
132
133
can be found [HERE][10]. Please note that [OpenCASCADE][2] requires further 3rd
party products, which are listed [HERE][11].
134
135

<!-- On Debian-based distributions, all of these can be installed
136
from the command line via:
137

138
```sh
139
sudo apt-get install tcllib tklib tcl-dev tk-dev libfreetype-dev libxt-dev libxmu-dev libxi-dev libgl1-mesa-dev libglu1-mesa-dev libfreeimage-dev libtbb-dev libgl2ps-dev
140
``` -->
141

Dennis Gläser's avatar
Dennis Gläser committed
142
### Building Frackit under Linux
143
After [OpenCASCADE][2] and the other requirements listed above have been installed,
Dennis Gläser's avatar
Dennis Gläser committed
144
145
146
clone this repository within your folder of choice by typing:

```sh
147
git clone https://git.iws.uni-stuttgart.de/tools/frackit.git
Dennis Gläser's avatar
Dennis Gläser committed
148
149
150
151
152
153
154
155
156
157
158
```

Then, create the build directory in which you want to compile the applications
and run cmake from it. For instance:

```sh
mkdir build
cd build
cmake ../
```

159
If cmake cannot find your installation of [OpenCASCADE][2], you probably installed it
Dennis Gläser's avatar
Dennis Gläser committed
160
161
162
163
164
165
166
167
168
169
170
171
172
173
into a non-standard location. In this case, you can define __HINTS__ for cmake to search
for it. In particular, you would have to change the line

```cmake
find_path(OCC_INC "Standard_Version.hxx" PATH_SUFFIXES opencascade include/opencascade)
```

to

```cmake
find_path(OCC_INC "Standard_Version.hxx" HINTS MY_OCC_INCLUDE_FOLDER)
```

in the _CMakeLists.txt_ file of the top folder of Frackit, substituting
174
MY_OCC_INCLUDE_FOLDER with the path to the source files of [OpenCASCADE][2]
Dennis Gläser's avatar
Dennis Gläser committed
175
on your system. The same has to be done for the required packages of
176
[OpenCASCADE][2], i.e. in the line
Dennis Gläser's avatar
Dennis Gläser committed
177
178
179
180
181
182

```cmake
find_library(OCC_LIB ${OCC}
             PATH_SUFFIXES lib ${OCC_SYS_NAME}/lib ${OCC_SYS_NAME}/vc8/lib)
```

183
you can define HINTS for cmake to find your installation folder of [OpenCASCADE][2].
184
Once cmake finished successfully, you could now compile the class documentation:
Dennis Gläser's avatar
Dennis Gläser committed
185
186
187
188
189

```sh
make doc_doxygen
```

190
and open it using a web browser, for example _chrome_:
Dennis Gläser's avatar
Dennis Gläser committed
191
192
193
194
195

```sh
google-chrome doc/doxygen/html/index.html
```

196
197
198
199
200
201
202
To build and run all unit tests, type

```sh
make build_tests
ctest
```

Dennis Gläser's avatar
Dennis Gläser committed
203
204
205
206
207
208
209
210
211
212
213
214
215
Moreover, you can build all example applications by typing

```sh
make build_example_applications
```

If this compiled successfully, you can go to the folder of the first example and
run it by typing:

```sh
cd appl/example1
./example1
```
216
217
218
219
220


License
=======

221
222
223
224
225
226
227
228
229
230
231
Frackit is licensed under the terms and conditions of the GNU General
Public License (GPL) version 3 or - at your option - any later
version. The GPL can be [read online][9] or in the [LICENSE.md](LICENSE.md) file
provided in the top folder of Frackit. See the file [LICENSE.md](LICENSE.md) for
full copying permissions.


Contributing
=============

Contributions are highly appreciated.
232
For bug reports, please file an [issue](https://git.iws.uni-stuttgart.de/tools/frackit/issues).
233
If you want to contribute with new features or improvements of existing code, please
234
235
236
237
238
239
240
241
242
243

* Get an account for our GitLab instance at https://git.iws.uni-stuttgart.de/
* Fork this project
* Push your changes to your fork on some branch.
* Open a merge request using the branch you pushed your changes to as the source branch and the master
of the Frackit repository as the target branch.
* Follow the discussion on the merge request to see what improvements should be done to the branch
before merging.
* If you have developer status you don't need to do a fork and you can create branches directly.

Dennis Gläser's avatar
Dennis Gläser committed
244
In this project, we follow the [styleguide][2] of the [DuMuX][0] project.
245
Please have a look at this before you start coding your contributions.
246

247
248
249
250
251
252

Ongoing Developments
====================

* Kernel for fracture network characterization (e.g. connectivity)
* Capabilities for translation of fracture networks into graphs, allowing for efficient characterization of the network based on its graph representation.
Dennis Gläser's avatar
Dennis Gläser committed
253
* Python bindings
254

255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
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

271
272
273
274
[0]: https://dumux.org
[1]: http://gmsh.info/
[2]: https://www.opencascade.com/content/download-center
[3]: https://www.opencascade.com/content/cad-assistant
275
276
277
278
[4]: https://git.iws.uni-stuttgart.de/tools/frackit/tree/master/appl/example3
[5]: https://git.iws.uni-stuttgart.de/tools/frackit/tree/master/appl/example1
[6]: https://git.iws.uni-stuttgart.de/tools/frackit/tree/master/appl/example2
[7]: https://git.iws.uni-stuttgart.de/tools/frackit/tree/master/appl/
Dennis Gläser's avatar
Dennis Gläser committed
279
[8]: http://www.doxygen.org/index.html
280
[9]: https://www.gnu.org/licenses/gpl-3.0.en.html
Dennis Gläser's avatar
Dennis Gläser committed
281
282
283
284

[10]: https://www.opencascade.com/doc/occt-6.9.1/overview/html/occt_dev_guides__building_cmake.html
[11]: https://www.opencascade.com/doc/occt-6.9.1/overview/html/occt_dev_guides__building_3rdparty_linux.html
[12]: https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/blob/master/doc/styleguide.md
Dennis Gläser's avatar
Dennis Gläser committed
285
[13]: https://git.iws.uni-stuttgart.de/dumux-pub/glaeser2020a
286
287
[14]: https://launchpad.net/~freecad-maintainers/+archive/ubuntu/occt-releases
[15]: https://www.freecadweb.org/
Dennis Gläser's avatar
Dennis Gläser committed
288
[16]: https://git.dev.opencascade.org/gitweb/?p=occt.git;a=snapshot;h=1630119c3a5ec5a3268ddf8775a7085b5f6b06de;sf=tgz