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

Feature/add readme mds

See merge request DennisGlaeser/frackit!45

CMakeLists.txt

@@ -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()

README.md

-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

doc/doxygen/mainpage.txt

@@ -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.
+
+ */

frackit/common/promotedtype.hh

@@ -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; };
 

frackit/entitynetwork/constraints.hh

@@ -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
      */

frackit/entitynetwork/containedentitynetwork.hh

@@ -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()); }

frackit/entitynetwork/containedentitynetworkinterface.hh

@@ -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;
 

frackit/entitynetwork/multigeometryentityset.hh

@@ -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)
     {

frackit/geometry/circle.hh

@@ -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,

frackit/geometry/direction.hh

@@ -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)
  */

frackit/sampling/quadrilateralsampler.hh

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