README.md 5.41 KB
Newer Older
1
2
3
4
5
6
7
8
9
<!--- Example picture --->
<p align="center">
    <img src="../../doc/img/example1_network.png" alt="frackit example 1" width="800"/>
</p>

Example 1
=========

In this exemplary application, a network of quadrilateral fractures is generated
Dennis Gläser's avatar
Dennis Gläser committed
10
11
12
within the unit cube (see image above). The main file containing the source code
to this example is the file `example1.cc` which is located in this folder.

13
14
Two main orientations are considered for the quadrilaterals, for both of which
a corresponding instance of the `QuadrilateralSampler` class is created.
Dennis Gläser's avatar
Dennis Gläser committed
15
For example, we instantiate an instance of this class by writing:
16
17

```cpp
Dennis Gläser's avatar
Dennis Gläser committed
18
19
20
static constexpr int worldDimension = 3;

using ctype = double;
21
using Distro = std::normal_distribution<ctype>;
Dennis Gläser's avatar
Dennis Gläser committed
22
23
24
25
26
27
28
29
using QuadSampler = QuadrilateralSampler<worldDimension>;

Box<ctype> domain(0.0, 0.0, 0.0, 1.0, 1.0, 1.0);
QuadSampler quadSampler(makeUniformPointSampler(domain),         // point sampler that samples the center points of the quadrilaterals
                        Distro(toRadians(0.0), toRadians(5.0)),  // strike angle: mean value & standard deviation
                        Distro(toRadians(0.0), toRadians(5.0)),  // dip angle: mean value & standard deviation
                        Distro(0.5, 0.1),                        // edge length: mean value & standard deviation
                        0.05);                                   // threshold for minimum edge length
30
31
32
33
34
35
```

The first constructor argument is a point sampler with which the center points of
the quadrilaterals are sampled. Here we use uniformly sampled points in the unit
cube, which is represented by an instance of the `Box` class,  stored in the
variable `domain`. The second and third arguments define the distributions for
Dennis Gläser's avatar
Dennis Gläser committed
36
the strike and dip angle (for details see the [class documentation][2]), where in this case we use uniform distributions with
37
38
39
40
a mean value of 0° and a standard deviation of 5°. The fourth argument is the
distribution to be used for sampling the edge lengths, while the last argument
defines a minimum value below which the edge length must not fall.

Dennis Gläser's avatar
Dennis Gläser committed
41
In the example, the quadrilaterals are sampled from the two samplers `quadSampler1` and
Dennis Gläser's avatar
Dennis Gläser committed
42
43
44
45
46
47
`quadSampler2`, using the `()` operator:

```cpp
auto quad = sampleIntoSet1 ? quadSampler1() : quadSampler2();
```

Dennis Gläser's avatar
Dennis Gläser committed
48
Here, we use the boolean variable `sampleIntoSet1` to determine from
Dennis Gläser's avatar
Dennis Gläser committed
49
50
which sampler we should sample the next quadrilateral (more details follow below).
The variable `quad` holds a new candidate for an entity of the network, however,
Dennis Gläser's avatar
Dennis Gläser committed
51
we want to enforce certain constraints such as a minimum distance between
Dennis Gläser's avatar
Dennis Gläser committed
52
53
54
entities. For this we use instances of the `EntityNetworkConstraints` class and
configure it as desired. For example, the constraints on entities of the same
orientation are defined in this example as follows:
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73

```cpp
EntityNetworkConstraints constraintsOnSelf;
constraintsOnSelf.setMinDistance(0.05);
constraintsOnSelf.setMinIntersectingAngle(toRadians(30.0));
constraintsOnSelf.setMinIntersectionMagnitude(0.05);
constraintsOnSelf.setMinIntersectionDistance(0.05);
```

In the main loop of quadrilateral generation, the fulfilment of these constraints is
evaluated against the other quadrilaterals with:

```cpp
auto& entitySet = sampleIntoSet1 ? entitySet1 : entitySet2;
if (!constraintsOnSelf.evaluate(entitySet, quad))
{ status.increaseRejectedCounter(); continue; }
```

where `entityset1` and `entitySet2` are of type `std::vector<Quadrilateral>` and
Dennis Gläser's avatar
Dennis Gläser committed
74
75
store all quadrilaterals that are accepted. The function `evaluate` of the
`EntityNetworkConstraints` class evaluates the constraints for `quad` against all
Dennis Gläser's avatar
Dennis Gläser committed
76
entities contained in `entitySet` and returns `true` only if no violation of
Dennis Gläser's avatar
Dennis Gläser committed
77
78
any of the defined constraints has been found. After an admissible quadrilateral
has been generated, the line
79
80
81
82
83
84
85
86
87

```cpp
// sample into the other set the next time
sampleIntoSet1 = !sampleIntoSet1;
```

at the end of the loop makes sure that a quadrilateral of the other orientation
is sampled next. In [Example 3][0] we will get to know how to use helper classes
that store different entity sets and automatically sample from various sampler
Dennis Gläser's avatar
Dennis Gläser committed
88
classes such that this can be written more easily.
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108

After the desired number of entities has been generated, the entities are cast
into an entity network using the builder class:

```cpp
EntityNetworkBuilder builder;
builder.addEntities(entitySet1);
builder.addEntities(entitySet2);

const auto network = builder.build();
```

This network can then be written to disk, for example in [Gmsh][1] (.geo) file format:

```cpp
GmshWriter writer(network);
writer.write("network", // filename of the .geo files (will add extension .geo automatically)
             0.1);      // element size to be used
```

Dennis Gläser's avatar
Dennis Gläser committed
109
110
111
112
113
114
115
116
117
Note that with the `EntityNetworkBuilder` class we have created a network that
solely carries information about the fracture entities. We have not defined any
domain in this example, the unit cube in the variable `domain` was only used to
sample the center points of the quadrilaterals. Thus, the geometry files written
by the `GmshWriter` also only contain data on the fracture entities. This can be
used in contexts where one is only interested in the fractures. In the following
examples we will see how to construct fracture networks embedded in one or more
(sub-)domains.

118
119
[0]: https://git.iws.uni-stuttgart.de/DennisGlaeser/frackit/tree/master/appl/example3
[1]: http://gmsh.info/
Dennis Gläser's avatar
Dennis Gläser committed
120
[2]: https://git.iws.uni-stuttgart.de/DennisGlaeser/frackit/blob/master/frackit/sampling/quadrilateralsampler.hh