Commit 0423ec04 authored by Dennis Gläser's avatar Dennis Gläser
Browse files

Merge branch 'feature/add-readme-mds' into 'master'

Feature/add readme mds

See merge request DennisGlaeser/frackit!45
parents 6a28e83b 20136de3
......@@ -18,8 +18,9 @@ set(CMAKE_CXX_FLAGS_RELWITHDEBINFO "$GXX_RELEASE_OPTS $GXX_RELEASE_WARNING_OPTS
set(CMAKE_BUILD_TYPE Release)
# Find OpenCascade
find_path(OCC_INC "Standard_Version.hxx" HINTS ~/Software/opencascade-7.3.0/occ-build/include/opencascade)
# PATH_SUFFIXES opencascade include/opencascade)
find_path(OCC_INC "Standard_Version.hxx"
PATH_SUFFIXES opencascade include/opencascade
HINTS ~/Software/opencascade-7.3.0/occ-build/include/opencascade)
if (OCC_INC)
include_directories( ${OCC_INC} )
......@@ -55,7 +56,9 @@ if (OCC_INC)
else()
set(OCC_LIBS)
foreach(OCC ${OCC_LIBS_REQUIRED})
find_library(OCC_LIB ${OCC} HINTS ~/Software/opencascade-7.3.0/occ-build/lin64/gcc/lib)
find_library(OCC_LIB ${OCC}
PATH_SUFFIXES lib ${OCC_SYS_NAME}/lib ${OCC_SYS_NAME}/vc8/lib
HINTS ~/Software/opencascade-7.3.0/occ-build/lin64/gcc/lib)
if(OCC_LIB)
list(APPEND OCC_LIBS ${OCC_LIB})
else()
......
This diff is collapsed.
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 using
[Doxygen][8] (see Installation notes).
Moreover, the [Examples][7] contained in this repository provide a good overview over
the capabilities of Frackit and can serve as a starting point to develop your own
application.
Installation
============
Please note that the following requirements need to be installed:
* OpenCascade (>= 7.3.0)
* CMake (>2.8.12)
* C, C++ compiler (C++17 required)
* Optional: Doxygen (>= 1.8)
### Installation of OpenCascade
Frackit requires the [OpenCascade][2] library to be installed on your system.
You can download the source code at https://www.opencascade.com/content/download-center,
and for details on the installation we refer to TODO:PUT_LINK.
### Building Frackit under Linux
After [OpenCascade][2] and the other requirements listed above have been installed,
clone this repository within your folder of choice by typing:
```sh
git clone https://git.iws.uni-stuttgart.de/DennisGlaeser/frackit.git
```
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 ../
```
If cmake cannot find your installation of [OpenCascade][2], you probably installed it
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
MY_OCC_INCLUDE_FOLDER with the path to the source files of [OpenCascade][2]
on your system. The same has to be done for the required packages of
[OpenCascade][2], i.e. in the line
```cmake
find_library(OCC_LIB ${OCC}
PATH_SUFFIXES lib ${OCC_SYS_NAME}/lib ${OCC_SYS_NAME}/vc8/lib)
```
you can define HINTS for cmake to find your installation folder of [OpenCascade][2].
Once cmake finished successfully, you could now compile the class documentation:
```sh
make doc_doxygen
```
and open it using a web browser, for example _chrome_:
```sh
google-chrome doc/doxygen/html/index.html
```
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
```
License
=======
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.
Before you start coding, please have a look at the [styleguide][doc/styleguide.md].
For bug reports, please file an [issue](https://git.iws.uni-stuttgart.de/DennisGlaeser/frackit/issues).
If you want to contribute with new features of improvements of existing code, please
* 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.
[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/
[8]: http://www.doxygen.org/index.html
[9]: https://www.gnu.org/licenses/gpl-3.0.en.html
......@@ -2,3 +2,26 @@
* \file
* \brief documentation for the doxygen main page
*/
/** \mainpage Frackit Documentation
Welcome to the Frackit documentation pages. This documentation has been
generated using <a href="http://www.doxygen.org/index.html">Doxygen</a>, a free
source code documentation system for documenting C/C++ code.
\section intro Introduction
Frackit is an open-source framework for the stochastic generation of fracture networks.
The implementation is written in C++ language and extensively uses
<a href="https://www.opencascade.com/content/download-center">OpenCascade</a>,
an open-source Computer Aided Design (CAD) library.
\section mods Modules
The best way to start is from the <a href="modules.html">Modules</a> page which gives
you access to the documentation by category.
\section features Features
An overview of all availabe parameters will be available soon.
*/
......@@ -40,7 +40,11 @@ struct PromotionTraits
using PromotedType = decltype(std::declval<T1>()+std::declval<T2>());
};
// Specialization for the case of two equal types
/*!
* \ingroup Common
* \brief Specialization of the PromotionTraits
* for the case of two equal types.
*/
template<class T1>
struct PromotionTraits<T1,T1> { typedef T1 PromotedType; };
......
......@@ -265,7 +265,7 @@ public:
* pointer to its original geometry type.
* \tparam T either a entity type or an entity set
* \param entityOrSet An entity or an entity set
* \param geo2 Pointer to a generic geometry type
* \param geo2Ptr Pointer to a generic geometry type
* \returns True if all constraints are fulfilled, false otherwise
*/
template<class T>
......@@ -281,7 +281,7 @@ public:
* to a generic geometry. Unfortunately, this requires
* parsing the pointer to its original geometry type.
* \tparam T either a entity type or an entity set
* \param geo1 Pointer to a generic geometry type
* \param geo1Ptr Pointer to a generic geometry type
* \param entityOrSet An entity or an entity set
* \returns True if all constraints are fulfilled, false otherwise
*/
......
......@@ -54,11 +54,11 @@ public:
/*!
* \brief Constructor.
* \param entityDim Dimension of the network entities
* \param fragmentList List containing all entity fragments
* \param fragmentIndexMap Map containing the fragments
* of a network, where each fragment
* is mapped to the index of the primary
* entity of the network.
* \param sdFragments The sub-domains, split into fragments by the entities
* \param entityFragments Contains the entity fragments of each sub-domain
* \param entityFragmentMaps Map containing the fragments of the sub-domains,
* where each fragment is mapped to the index of the
* primary entity of the network from which is was created.
*/
ContainedEntityNetwork(int entityDim,
int domainDim,
......@@ -83,21 +83,21 @@ public:
/*!
* \brief Returns the fragments of a sub-domain
* \param subDomainIdx The index of the sub-domain
* \param subDomainId The id of the sub-domain
*/
const TopTools_ListOfShape& subDomainFragments(Id subDomainId) const override
{ return subDomainFragments_.at(subDomainId.get()); }
/*!
* \brief Returns the entity fragments of the network defined for a sub-domain
* \param subDomainIdx The index of the sub-domain
* \param subDomainId The id of the sub-domain
*/
const TopTools_ListOfShape& subDomainEntityFragments(Id subDomainId) const override
{ return subDomainEntityFragments_.at(subDomainId.get()); }
/*!
* \brief Returns the map which maps each fragment the network of a sub-domain to its primary entity index.
* \param subDomainIdx The index of the sub-domain
* \param subDomainId The id of the sub-domain
*/
const TopTools_DataMapOfShapeInteger& subDomainEntityFragmentsIndexMap(Id subDomainId) const override
{ return subDomainEntityFragmentIndexMap_.at(subDomainId.get()); }
......
......@@ -75,19 +75,19 @@ public:
/*!
* \brief Returns the fragments of a sub-domain
* \param subDomainIdx The index of the sub-domain
* \param subDomainId The id of the sub-domain
*/
virtual const TopTools_ListOfShape& subDomainFragments(Id subDomainId) const = 0;
/*!
* \brief Returns the entity fragments of the network defined for a sub-domain
* \param subDomainIdx The index of the sub-domain
* \param subDomainId The id of the sub-domain
*/
virtual const TopTools_ListOfShape& subDomainEntityFragments(Id subDomainId) const = 0;
/*!
* \brief Returns the map which maps each fragment the network of a sub-domain to its primary entity index.
* \param subDomainIdx The index of the sub-domain
* \param subDomainId The id of the sub-domain
*/
virtual const TopTools_DataMapOfShapeInteger& subDomainEntityFragmentsIndexMap(Id subDomainId) const = 0;
......
......@@ -62,7 +62,7 @@ public:
/*!
* \brief Adds an entity to the set with the given id.
* \param entity The entity to be added.
* \param if The id of the entity set.
* \param id The id of the entity set.
*/
template<class Entity>
void addEntity(const Entity& entity, const Id& id)
......@@ -103,7 +103,7 @@ public:
/*!
* \brief Adds an entity to the set with the given id.
* \param entity Pointer to the abstract geometry base class
* \param if The id of the entity set.
* \param id The id of the entity set.
*/
void addEntity(std::shared_ptr<Geometry> entity, const Id& id)
{
......
......@@ -73,6 +73,7 @@ public:
* \param center The center point of the circle
* \param normal The normal direction of the plane
* the circle is embedded in
* \param radius The radius of the circle
*/
Circle(const Point& center,
const Direction& normal,
......
......@@ -217,7 +217,7 @@ private:
* \relates Direction
*
* \param s std::ostream to write to
* \param v Direction to write
* \param d Direction to write
*
* \returns the output stream (s)
*/
......@@ -234,7 +234,7 @@ std::ostream& operator<< (std::ostream& s, const Direction<CT, 1>& d)
* \relates Direction
*
* \param s std::ostream to write to
* \param v Direction to write
* \param d Direction to write
*
* \returns the output stream (s)
*/
......
......@@ -104,7 +104,7 @@ public:
* \param strikeDistro The distribution used for the strike angle
* \param dipDistro The distribution used for the dip angle
* \param edgeDistro The distribution used for the edge length
* \minEdgeLength Minimum allowed edge length
* \param minEdgeLength Minimum allowed edge length
* \note The edge distribution is sampled until an admissible value
* above the minimum allowed edge length is obtained. Thus,
* if you choose a high minimum length, depending on the chosen
......
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