Commit 1703f77b authored by Dennis Gläser's avatar Dennis Gläser
Browse files

[readme] first draft of main readme

parent e0f5c0ca
TODO
====
<!--- Example picture --->
<p align="center">
<img src="doc/img/example3_network.png" alt="frackit example" width="800"/>
</p>
Doc this thing.
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
[OpenCascade][2], an open-source Computer Aided Design (CAD) library.
The geometries 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.
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 for flow and transport in porous media [DuMuX][0].
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 (see e.g. https://arxiv.org/pdf/1909.05052.pdf). An example for this
can be found in [example 3][4] of this repository.
General Concept
===============
### Step 1: sampling
The generation of the fracture networks occurs by randomly sampling instances of the
desired fracture geometry on the basis of probability distribution functions, which
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.
### Step 2: checking constraints
After the generation of a new candidate for a fracture, a number of constraints can
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.
### Step 3: fragmentation of the network
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.
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:
* [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 of a fractured porous medium.
* [Example 3][4] Generation of a network consisting of both disks and quadrilaterals, embedded in one layer of a domain that composed of three layers.
Documentation
=============
A class documentation can be generated from the source code (see Installation notes).
Moreover, the [Examples][7] contained in this repository provide a good overview over
the capabilities of Frackit. Moreover, extensive comments can be found in the source
code to these exemplary applications.
Installation
============
TODO:
License
=======
[0]: https://dumux.org
[1]: http://gmsh.info/
[2]: https://www.opencascade.com/content/download-center
[3]: https://www.opencascade.com/content/cad-assistant
[4]: https://git.iws.uni-stuttgart.de/DennisGlaeser/frackit/tree/master/appl/example3
[5]: https://git.iws.uni-stuttgart.de/DennisGlaeser/frackit/tree/master/appl/example1
[6]: https://git.iws.uni-stuttgart.de/DennisGlaeser/frackit/tree/master/appl/example2
[7]: https://git.iws.uni-stuttgart.de/DennisGlaeser/frackit/tree/master/appl/
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment