README.md 16 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
What is Frackit?
================

9
10
11
12
13
14
15
16
17
18
19
20
Frackit is an open-source software framework for the stochastic generation of fracture networks,
in which the fractures are represented by geometric entities of codimension one. That is,
two-dimensional geometries in three-dimensional space, or one-dimensional geometries in
two-dimensional space. Its main purpose is to provide a means of generating networks with
specific statistical characteristics to be used in conjunction with numerical models, for
instance, in investigations on the impact of fracture network topologies on the hydraulic
or mechanical properties of fractured porous media.

The code is written in C++ language, but Python bindings are available that allow users to
access all functionalities from Python after their installation. Frackit makes extensive use
of [OpenCASCADE][2], an open-source Computer Aided Design (CAD) library, which provides
great flexibility concerning the geometries that can be used.
21

22
The geometric data generated by Frackit can be exported into a number of standard CAD
23
24
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],
25
26
27
28
29
or [Gmsh][1], a three-dimensional finite element mesh generator.

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

30
31
32
33
34
35
36
37
38
39
40
41
42
43
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
Dennis Gläser's avatar
Dennis Gläser committed
44
45
(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
46
47
48
[DuMuX][0] to perform simulations on the generated fracture networks.

The following picture shows an exemplary result for a single-phase simulation
49
on a fracture network generated with Frackit, and it depicts the pressure distribution
50
on the fractures as well as the fluid velocities in the domain:
51
52
53
54
55

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

Dennis Gläser's avatar
Dennis Gläser committed
56
57
58
The source code to the flow simulation shown in the above figure, including installation
instructions, can be found [here][13]. Furthermore, [Example 3][4] of the Frackit examples
contains the code to generating a fracture network on the above domain geometry.
59
60
61
62

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

63
64
65
66
67
68
Frackit does not prescribe a certain program flow, instead, users are motivated to implement
their own applications using the provided functions, classes and concepts. These comprise
functionality related to the stochastic sampling of a fracture entity, checking geometric
constraints, and fragmentation of a collection of entities to determine connectivity
information.

Dennis Gläser's avatar
Dennis Gläser committed
69
### Geometry Sampling
70
The generation of the fracture networks occurs by randomly sampling instances of the
71
72
73
74
desired fracture geometry on the basis of probability distributions for the parameters
that describe their orientation and/or spatial location. In the code this is realized
in sampler classes, into which the desired statistical properties can be injected and
from which entity candidates can then be sampled.
75

Dennis Gläser's avatar
Dennis Gläser committed
76
### Constraints Evaluation
Dennis Gläser's avatar
Dennis Gläser committed
77
After the generation of a new candidate for a fracture entity, a number of constraints can
78
79
80
81
82
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
83
minimum intersection angle, and a minimum distance of the intersection geometry to the boundaries
84
of the intersecting entities. If the user-defined constraints are not fulfilled, the candidate
85
86
can be rejected. Frackit provides a class that allows users to define and check for geometric
constraints, but one can also implement custom constraints using the provided geometric algorithms.
87

Dennis Gläser's avatar
Dennis Gläser committed
88
### Fragmentation of the network
89
90
91
92
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.

93
94
95
The modular design of the above-mentioned building blocks enables users to fully customize
each step to their needs. In order to provide an overview of the capabilities of Frackit
and how to use them, various exemplary applications are contained in this repository.
96

Dennis Gläser's avatar
Dennis Gläser committed
97
98
99
100
### Example applications

This repository provides a number of examples that may help you to get familiar with the basic concepts of Frackit.
These are not meant to represent realistic scenarios or lead to realistic network topologies, but are rather designed
101
such that the execution time is low and that a wide range of functionalities of Frackit is covered.
Dennis Gläser's avatar
Dennis Gläser committed
102

103
* [Example 1][5] Generation of a simple network consisting of quadrilaterals with two main orientations.
Dennis Gläser's avatar
Dennis Gläser committed
104
105
* [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.
Dennis Gläser's avatar
Dennis Gläser committed
106
* [Example 4][17] Generation of a network consisting of polygonal entities, distributed around a tunnel structure that is embedded in a spherical domain.
107

108

109
110
111
Documentation
=============

Dennis Gläser's avatar
Dennis Gläser committed
112
113
A class documentation can be generated from the source code using
[Doxygen][8] (see Installation notes).
Dennis Gläser's avatar
Dennis Gläser committed
114
Moreover, the [examples][7] contained in this repository provide a good overview over
Dennis Gläser's avatar
Dennis Gläser committed
115
the capabilities of Frackit and can serve as a starting point to develop your own
Dennis Gläser's avatar
Dennis Gläser committed
116
application. While the example descriptions focus on the implementation in C++, Python
117
implementations for all examples are also available in the respective example folders.
118
119
120
121
122


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

123
124
125
126
127
128
Please note that a number of packages are required in order to install Frackit on your
system. However, you can also run Frackit inside a [docker container](https://www.docker.com/)
using the image provided in this repository. For more details, please have a look at
the description in [docker/README.md](https://git.iws.uni-stuttgart.de/tools/frackit/tree/master/docker/README.md).

For a manual installation, the following requirements need to be installed:
Dennis Gläser's avatar
Dennis Gläser committed
129

130
* OpenCASCADE (>= 7.3.0)
Dennis Gläser's avatar
Dennis Gläser committed
131
* CMake (>3.0)
Dennis Gläser's avatar
Dennis Gläser committed
132
133
* C, C++ compiler (C++17 required)
* Optional: Doxygen (>= 1.8)
134
135
* Optional: python3 (for python bindings)
* Optional: pybind11 (for python bindings)
Dennis Gläser's avatar
Dennis Gläser committed
136

137
Note that testing of Frackit occurs with OpenCASCADE 7.3.0 and 7.5.0, using the tarballs of the respective
138
139
140
release tags in the OpenCASCADE development portal (for more infos see below). We recommend to use these tags,
or the Debian packages (see below), as we have experienced issues with version 7.4 as well as some of the later
tags of the 7.3 series.
141

142
143
### Installation of OpenCASCADE
Frackit requires parts of the [OpenCASCADE][2] library to be installed on your system.
144
Thanks to the ["FreeCAD maintainers" team][15], there are Debian packages of
Dennis Gläser's avatar
Dennis Gläser committed
145
146
[OpenCASCADE][2] available (see [this link][14]). To install the required packages
on Ubuntu, you have to add the repository by typing
147
148
149
150
151
152
153
154
155
156
157
158

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

159
If you prefer building [OpenCASCADE][2] from the sources, you can download the
160
161
162
163
source code [HERE][2] after registration. You can also browse the git repository
online, following the respective link provided at
[dev.opencascade.org/resources](https://dev.opencascade.org/index.php?q=home/resources).
From there, you can download the release tarballs. [Click here][16] to directly
Dennis Gläser's avatar
Dennis Gläser committed
164
download the tarball of the 7.3 release.
165
166
167
<!-- 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
168
development portal at http://dev.opencascade.org. Click [this link][16] to download
169
the tarball for the version 7.3 release. -->
170
171
172
173
174
175
176
177
178
179
Details on building [OpenCASCADE][2] can be found [HERE][10]. Please note that for
a complete build, [OpenCASCADE][2] requires further third party products, which are
listed [HERE][11]. However, Frackit only uses some of the modules of [OpenCASCADE][2]
and for a minimal installation no third party products are required. To deactivate the
modules that are not needed, set the corresponding cmake variables

```sh
BUILD_MODULE_ApplicationFramework=0
BUILD_MODULE_DataExchange=0
BUILD_MODULE_Draw=0
180
BUILD_MODULE_Visualization=0
181
182
183
184
185
186
187
188
189
190
191
192
193
```

for the configuration step of [OpenCASCADE][2]. For instance, after you downloaded the
[OpenCASCADE][2] source files, go into the respective folder and type

```sh
mkdir build
cd build
cmake -DBUILD_MODULE_ApplicationFramework=0 -DBUILD_MODULE_DataExchange=0 -DBUILD_MODULE_Draw=0 -DBUILD_MODULE_Visualization=0 ../
make install
```

to install only the required modules on your system.
194
195

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

198
```sh
199
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
200
``` -->
201

202
203
### Installation of pybind11

204
If you want to use the python bindings you need to install pybind11. You can get it from
205
the GitHub repository at [github.com/pybind/pybind11/](https://github.com/pybind/pybind11/)
206
207
208
and manually install it. Alternatively, you can install it via the command line (here shown for Ubuntu users)

```bash
209
sudo apt-get install pybind11-dev
210
211
```

212
However, it is not guaranteed that the version of pybind11 that comes with the package
213
214
contains all features used by `Frackit`. Currently, testing occurs with version pybind11 version 2.6.
Therefore, we recommend to clone the respective branch from the repository and maually install it.
215

Dennis Gläser's avatar
Dennis Gläser committed
216
### Building Frackit under Linux
217
After [OpenCASCADE][2] and the other requirements listed above have been installed,
Dennis Gläser's avatar
Dennis Gläser committed
218
219
220
clone this repository within your folder of choice by typing:

```sh
221
git clone https://git.iws.uni-stuttgart.de/tools/frackit.git
Dennis Gläser's avatar
Dennis Gläser committed
222
223
224
225
226
227
228
229
230
231
232
```

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

233
If cmake cannot find your installation of [OpenCASCADE][2], you probably installed it
234
235
into a non-standard location. In this case, tell cmake your installation folder by
setting the variable `OCC_INSTALL_DIR`:
Dennis Gläser's avatar
Dennis Gläser committed
236

237
238
```sh
cmake -DOCC_INSTALL_DIR=PATH_TO_YOUR_OCC_INSTALLATION ../
Dennis Gläser's avatar
Dennis Gläser committed
239
```
240
Once cmake finished successfully, you could now compile the class documentation:
Dennis Gläser's avatar
Dennis Gläser committed
241
242
243
244
245

```sh
make doc_doxygen
```

246
and open it using a web browser, for example _chrome_:
Dennis Gläser's avatar
Dennis Gläser committed
247
248
249
250
251

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

252
253
254
255
256
257
258
To build and run all unit tests, type

```sh
make build_tests
ctest
```

259
This also builds all example applications, and if you want to build them exclusively you can type 
Dennis Gläser's avatar
Dennis Gläser committed
260
261

```sh
262
make build_example_tests
Dennis Gläser's avatar
Dennis Gläser committed
263
264
```

265
After successful compilation, you can go to the folder of the first example and
Dennis Gläser's avatar
Dennis Gläser committed
266
267
268
269
270
271
run it by typing:

```sh
cd appl/example1
./example1
```
272

273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
To install the Frackit python package on your system, go back to the `build` folder and type

```sh
make
make install_python
```

If this finished successfully, you can, for instance, run the python implementation of
example1 by heading to the examples folder (in the source tree):

```sh
cd ../appl/example1
python3 example1.py
```

288
289
290
291

License
=======

292
293
294
295
296
297
298
299
300
301
302
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.
303
For bug reports, please file an [issue](https://git.iws.uni-stuttgart.de/tools/frackit/issues).
304
If you want to contribute with new features or improvements of existing code, please
305
306
307
308
309
310
311
312
313
314

* 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
315
In this project, we follow the [styleguide][2] of the [DuMuX][0] project.
316
Please have a look at this before you start coding your contributions.
317

318

319
Future Developments
320
321
====================

322
* Parallelization of the code
Dennis Gläser's avatar
Dennis Gläser committed
323
324
* Kernel for detailed characterizations of the generated fracture networks (e.g. connectivity, density, etc.)
* Capabilities for translation of fracture networks into graphs, allowing for efficient characterization of a network based on its graph representation.
325

326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
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

342
343
344
345
[0]: https://dumux.org
[1]: http://gmsh.info/
[2]: https://www.opencascade.com/content/download-center
[3]: https://www.opencascade.com/content/cad-assistant
346
347
348
349
[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
350
[8]: http://www.doxygen.org/index.html
351
[9]: https://www.gnu.org/licenses/gpl-3.0.en.html
Dennis Gläser's avatar
Dennis Gläser committed
352
353
354
355

[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
356
[13]: https://git.iws.uni-stuttgart.de/dumux-pub/glaeser2020a
357
358
[14]: https://launchpad.net/~freecad-maintainers/+archive/ubuntu/occt-releases
[15]: https://www.freecadweb.org/
Dennis Gläser's avatar
Dennis Gläser committed
359
[16]: https://git.dev.opencascade.org/gitweb/?p=occt.git;a=snapshot;h=1630119c3a5ec5a3268ddf8775a7085b5f6b06de;sf=tgz
Dennis Gläser's avatar
Dennis Gläser committed
360
[17]: https://git.iws.uni-stuttgart.de/tools/frackit/tree/master/appl/example4