Merge pull request #3 from esa/vertices-checking

Mesh checking utility
esa · Nov 14, 2022 · f42cd51 · f42cd51
2 parents 19f61fa + b5e3ca5
commit f42cd51
Show file tree

Hide file tree

Showing 31 changed files with 1,174 additions and 480 deletions.
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -10,14 +10,9 @@ include(CMakeDependentOption)
 # PARALLELIZATION OPTIONS AND LOGGING
 #####################################
 # Parallelization on the HOST
-set(PARALLELIZATION_HOST "CPP" CACHE STRING "Host parallelization chosen by the user
+set(POLYHEDRAL_GRAVITY_PARALLELIZATION "CPP" CACHE STRING "Host parallelization chosen by the user
  (CPP= Serial, OMP = OpenMP, TBB = Intel Threading Building Blocks")
-set_property(CACHE PARALLELIZATION_HOST PROPERTY STRINGS CPP, OMP, TBB)
-
-# Parallelization on the DEVICE
-set(PARALLELIZATION_DEVICE "CPP" CACHE STRING "Device parallelization chosen by the user
- (CPP= Serial, OMP = OpenMP, TBB = Intel Threading Building Blocks")
-set_property(CACHE PARALLELIZATION_DEVICE PROPERTY STRINGS CPP, OMP, TBB)
+set_property(CACHE POLYHEDRAL_GRAVITY_PARALLELIZATION PROPERTY STRINGS CPP, OMP, TBB)
 
 # Enforce to use an already installed tbb library instead of compiling from source
 option(USE_LOCAL_TBB "Uses the local tbb installation rather than on using the automatically fetched version from
@@ -70,20 +65,14 @@ include(xsimd)
 # Get a version of tbb from the github repository, simplifies compilation for the user since tbb does not need to be
 # preinstalled but rather gets automatically set up via CMake
 # Nevertheless, there is still the option to enforce to use a local installation if one exists
-if (NOT USE_LOCAL_TBB AND (${PARALLELIZATION_HOST} STREQUAL "TBB" OR ${PARALLELIZATION_DEVICE} STREQUAL "TBB"))
+if (NOT USE_LOCAL_TBB AND ${POLYHEDRAL_GRAVITY_PARALLELIZATION} STREQUAL "TBB")
     include(tbb)
     thrust_set_TBB_target(tbb)
 endif ()
 
 # Thrust set-up i.e. the parallelization library, create targets according to the users specification
-thrust_create_target(Thrust HOST ${PARALLELIZATION_HOST} DEVICE ${PARALLELIZATION_DEVICE})
-message(STATUS "Set Parallelization: HOST ${PARALLELIZATION_HOST} DEVICE ${PARALLELIZATION_DEVICE}")
-
-# This definitions will set the main eval(..) routine to be executed on the DEVICE if the users has given
-# an option parallelize on the Device
-if(NOT PARALLELIZATION_DEVICE STREQUAL "CPP")
-    add_compile_definitions(DEVICE)
-endif()
+thrust_create_target(Thrust HOST CPP DEVICE ${POLYHEDRAL_GRAVITY_PARALLELIZATION})
+message(STATUS "Set Parallelization: HOST CPP DEVICE ${POLYHEDRAL_GRAVITY_PARALLELIZATION}")
 
 ################################
 # Building the Polyhedral Libray

diff --git a/README.md b/README.md
@@ -5,20 +5,30 @@
 
 Implementation of the Polyhedral Gravity Model in C++ 17.
 
-The implementation is based on the paper [Tsoulis, D., 2012. Analytical computation of the full gravity tensor of a homogeneous arbitrarily shaped polyhedral source using line integrals. Geophysics, 77(2), pp.F1-F11.](http://dx.doi.org/10.1190/geo2010-0334.1)
+The implementation is based on the
+paper [Tsoulis, D., 2012. Analytical computation of the full gravity tensor of a homogeneous arbitrarily shaped polyhedral source using line integrals. Geophysics, 77(2), pp.F1-F11.](http://dx.doi.org/10.1190/geo2010-0334.1)
 and its corresponding [implementation in FORTRAN](https://software.seg.org/2012/0001/index.html).
 
-Supplementary details can be found in the more recent paper [TSOULIS, Dimitrios; GAVRIILIDOU, Georgia. A computational review of the line integral analytical formulation of the polyhedral gravity signal. Geophysical Prospecting, 2021, 69. Jg., Nr. 8-9, S. 1745-1760.](https://doi.org/10.1111/1365-2478.13134)
+Supplementary details can be found in the more recent
+paper [TSOULIS, Dimitrios; GAVRIILIDOU, Georgia. A computational review of the line integral analytical formulation of the polyhedral gravity signal. Geophysical Prospecting, 2021, 69. Jg., Nr. 8-9, S. 1745-1760.](https://doi.org/10.1111/1365-2478.13134)
 and its corresponding [implementation in MATLAB](https://github.com/Gavriilidou/GPolyhedron),
 which is strongly based on the former implementation in FORTRAN.
 
-## Documentation
+### Results and Plots
 
-The full extensive documentation can be found on [readthedocs](https://polyhedral-gravity-model-cpp.readthedocs.io/en/latest/).
+Some exemplary results and plots are stored in the
+[jupyter notebook](https://github.com/esa/polyhedral-gravity-model/blob/vertices-checking/script/polyhedral-gravity.ipynb).
+It also provides a good introduction to the application of
+the python interface.
 
+## Documentation (readthedocs)
+
+The full extensive documentation can be found
+on [readthedocs](https://polyhedral-gravity-model-cpp.readthedocs.io/en/latest/).
 
 ## Requirements
-The project uses the following dependencies, 
+
+The project uses the following dependencies,
 all of them are **automatically** set-up via CMake:
 
 - GoogleTest 1.11.0 (only required for testing)
@@ -30,6 +40,15 @@ all of them are **automatically** set-up via CMake:
 
 ## Python interface
 
+### conda
+
+The python interface can be easily installed with
+[conda](https://anaconda.org/conda-forge/polyhedral-gravity-model):
+
+    conda install -c conda-forge polyhedral-gravity-model
+
+### pip
+
 Use pip to install the python interface in your local python runtime.
 The module will be build using CMake and the using the above
 requirements. Just execute in repository root:
@@ -51,20 +70,22 @@ CMake and then follow these steps:
 
 The following options are available:
 
-|         Name (Default)         |                                                       Options and Remark                                                      |
-|:------------------------------:|:-----------------------------------------------------------------------------------------------------------------------------:|
-|  PARALLELIZATION_HOST (`CPP`)  |             `CPP` = Serial Execution on Host, `OMP`/ `TBB` = Parallel Execution on Host with OpenMP or Intel's TBB              |
-| PARALLELIZATION_DEVICE (`CPP`) | `CPP`= Serial Execution on Device, `OMP`/ `TBB` = Parallel Execution on Device with OpenMP or Intel's TBB |
-|      LOGGING_LEVEL (`2`)       |                          `0`= TRACE, `1`=DEBUG, `2`=INFO, `3`=WARN, `4`=ERROR, `5`=CRITICAL, `6`=OFF                          |
+|                             Name (Default) | Options                                                                                    |
+|-------------------------------------------:|:-------------------------------------------------------------------------------------------|
+| POLYHEDRAL_GRAVITY_PARALLELIZATION (`CPP`) | `CPP` = Serial Execution / `OMP` or `TBB` = Parallel Execution with OpenMP or Intel\'s TBB |
+|                        LOGGING_LEVEL (`2`) | `0` = TRACE/ `1` = DEBUG/ `2` = INFO / `3` = WARN/ `4` = ERROR/ `5` = CRITICAL/ `6` = OFF  |
+|                      USE_LOCAL_TBB (`OFF`) | Use a local installation of `TBB` instead of setting it up via `CMake`                     |
+|      BUILD_POLYHEDRAL_GRAVITY_DOCS (`OFF`) | Build this documentation                                                                   |
+|      BUILD_POLYHEDRAL_GRAVITY_TESTS (`ON`) | Build the Tests                                                                            |
+|   BUILD_POLYHEDRAL_PYTHON_INTERFACE (`ON`) | Build the Python interface                                                                 |
 
-During testing the combination PARALLELIZATION_HOST=`CPP` and PARALLELIZATION_DEVICE=`TBB`
-has been the most performant.
+During testing POLYHEDRAL_GRAVITY_PARALLELIZATION=`TBB` has been the most performant.
 It is further not recommend to change the LOGGING_LEVEL to something else than `INFO=2`.
 
 The recommended CMake command would look like this (we only need to change `PARALLELIZATION_DEVICE`, since
 the defaults of the others are already correctly set):
 
-    cmake .. -DPARALLELIZATION_DEVICE="TBB"
+    cmake .. -POLYHEDRAL_GRAVITY_PARALLELIZATION="TBB"
 
 ## Execution C++
 
@@ -91,14 +112,15 @@ Further one must specify the name of the .csv output file.
 ---
 gravityModel:
   input:
-    polyhedron:                                 #polyhedron source-file(s)
-      - "../example-config/data/tsoulis.node"   #.node contains the vertices
-      - "../example-config/data/tsoulis.face"   #.face contains the triangular faces
-    density: 2670.0                             #constant density in [kg/m^3]
-    points:                                     #Location of the computation point(s) P
-      - [0, 0, 0]                               #Here it is situated at the origin
+    polyhedron: #polyhedron source-file(s)
+      - "../example-config/data/tsoulis.node"   # .node contains the vertices
+      - "../example-config/data/tsoulis.face"   # .face contains the triangular faces
+    density: 2670.0                             # constant density in [kg/m^3]
+    points: # Location of the computation point(s) P
+      - [ 0, 0, 0 ]                             # Here it is situated at the origin
+    check_mesh: true                            # Fully optional, enables input checking (not given: false)
   output:
-    filename: "gravity_result.csv"              #The name of the output file 
+    filename: "gravity_result.csv"              # The name of the output file 
 
 ````
 
@@ -124,6 +146,12 @@ ASCII and binary format) are e.g.:
 - [Meshio](https://github.com/nschloe/meshio) for Python
 - [OpenMesh](https://openmesh-python.readthedocs.io/en/latest/readwrite.html) for Python
 
+The vertices in the input mesh file must be ordered so that the plane unit normals point outwards of the polyhedron for
+every face.
+One can use the program input-checking procedure to ensure the correct format. This method is activated via the
+corresponding configuration option and uses the Möller–Trumbore intersection algorithm. Notice that this algorithm is a
+quadratic complexity, so the check should only be utilized in case of uncertainty.
+
 ### Output
 
 The calculation outputs the following parameters for every Computation Point _P_:
@@ -135,6 +163,7 @@ The calculation outputs the following parameters for every Computation Point _P_
 | Vxx, Vyy, Vzz, Vxy, Vxz, Vyz |      1/s^2      |   The spatial rate of change of the gravitational accleration    |
 
 ## Testing C++
+
 The project uses GoogleTest for testing. In oder to execute those
 tests just execute the following command in the build directory:
 

diff --git a/cmake/pybind11.cmake b/cmake/pybind11.cmake
@@ -10,6 +10,8 @@ if (${pybind11_FOUND})
 
 else()
 
+    message(STATUS "Using pybind11 from git repository")
+
     #Fetches the version 2.9.2 from the official github of pybind11
     FetchContent_Declare(pybind11
             GIT_REPOSITORY https://github.com/pybind/pybind11

diff --git a/cmake/spdlog.cmake b/cmake/spdlog.cmake
@@ -6,10 +6,12 @@ find_package(spdlog 1.10.0 QUIET)
 
 if (${spdlog_FOUND})
 
-    message(STATUS "Using local spdlog installation")
+    message(STATUS "Using existing spdlog installation")
 
 else()
 
+    message(STATUS "Using spdlog from git repository")
+
     #Fetches the version 1.10.0 for spdlog
     FetchContent_Declare(spdlog
             GIT_REPOSITORY https://github.com/gabime/spdlog.git

diff --git a/cmake/thrust.cmake b/cmake/thrust.cmake
@@ -15,7 +15,7 @@ find_package(Thrust 1.16.0 QUIET)
 
 if (${Thrust_FOUND})
 
-    message(STATUS "Using local thrust installation")
+    message(STATUS "Using existing thrust installation")
 
 else()
     message(STATUS "Using thrust from git repository")

diff --git a/cmake/xsimd.cmake b/cmake/xsimd.cmake
@@ -7,10 +7,12 @@ find_package(xsimd 8.1.0 QUIET)
 
 if (${xsimd_FOUND})
 
-    message(STATUS "Using local xsimd installation")
+    message(STATUS "Using existing xsimd installation")
 
 else()
 
+    message(STATUS "Using xsimd from git repository")
+
     #Fetches the version 8.1.0 from the official github of tbb
     FetchContent_Declare(xsimd
             GIT_REPOSITORY https://github.com/xtensor-stack/xsimd.git

diff --git a/cmake/yaml.cmake b/cmake/yaml.cmake
@@ -6,7 +6,7 @@ find_package(yaml-cpp 0.7.0 QUIET)
 
 if (${yaml-cpp_FOUND})
 
-    message(STATUS "Using local yaml-cpp installation")
+    message(STATUS "Using existing yaml-cpp installation")
 
 else()
 

diff --git a/docs/api/calculation.rst b/docs/api/calculation.rst
@@ -9,8 +9,17 @@ since it contains the important function :code:`evaluate(..)`
 used evaluation of the polyhedral gravity model at computation
 point(s) P.
 
+Further, it implements the `Möller–Trumbore intersection algorithm <https://en.wikipedia.org/wiki/Möller–Trumbore_intersection_algorithm>`__
+capable of checking if the plane unit normals of the polyhedron are pointing outwards.
 
-Documentation
--------------
 
-.. doxygennamespace:: polyhedralGravity::GravityModel
+GravityModel
+------------
+
+.. doxygennamespace:: polyhedralGravity::GravityModel
+
+
+MeshChecking
+-----------
+
+.. doxygennamespace:: polyhedralGravity::MeshChecking
diff --git a/docs/api/python.rst b/docs/api/python.rst
@@ -1,6 +1,12 @@
 Python API
 ==========
 
+polyhedral_gravity
+------------------
+
+Computes the full gravity tensor for a given constant density polyhedron which consists of some
+vertices and triangular faces at given computation points
+
 .. py::module:: polyhedral_gravity
 
 Computes the full gravity tensor for a given constant density polyhedron which consists of some vertices and
@@ -57,3 +63,48 @@ triangular faces at a given computation point :math:`P`
    :param List[List[float[3]]] computation_points: multiple cartesian computation points :math:`P`
    :return: list of tuple of potential, acceleration, and second derivative tensor
    :rtype: List[Tuple[float, List[float[3]], List[float[6]]]]
+
+
+utility
+~~~~~~~
+
+This submodule contains useful utility functions like parsing meshes
+or checking if the polyhedron's mesh plane unit normals point outwards
+like it is required by the polyhedral-gravity model.
+
+.. py:function:: read(input_files)
+    :noindex:
+
+    Reads a polyhedron from a mesh file. The vertices and faces are read from input
+    files (either .node/.face, mesh, .ply, .off, .stl). File-Order matters in case of the first option!
+
+    :param List[str] input_files: polyhedral source files
+    :return: tuple of vertices (N, 3) (floats) and faces (N, 3) (ints)
+    :rtype: Tuple[List[List[float[3]]], List[List[int[3]]]]
+
+.. py:function:: check_mesh(vertices, faces)
+    :noindex:
+
+    Checks if no triangles of the polyhedral mesh are degenerated by checking that their surface area
+    is greater zero.
+    Further, Checks if all the polyhedron's plane unit normals are pointing outwards.
+    Reads a polyhedron from a mesh file
+
+    :param List[List[float[3]]] vertices: vertices of the polyhedron
+    :param List[List[int[3]]] faces: faces of the polyhedron
+    :return: True if no triangle is degenerate and the polyhedron's plane unit normals are all pointing outwards.
+    :rtype: Bool
+
+.. py:function:: check_mesh(input_files)
+    :noindex:
+
+    Checks if no triangles of the polyhedral mesh are degenerate by checking that their surface area
+    is greater zero.
+    Further, Checks if all the polyhedron's plane unit normals are pointing outwards.
+    Reads a polyhedron from a mesh file. The vertices and faces are read from input
+    files (either .node/.face, mesh, .ply, .off, .stl). File-Order matters in case of the first option!
+
+    :param List[str] input_files: polyhedral source files
+    :return: True if no triangle is degenerate and the polyhedron's plane unit normals are all pointing outwards.
+    :rtype: Bool
+
diff --git a/docs/build.rst b/docs/build.rst
@@ -1,5 +1,5 @@
-Requirements and Build
-======================
+Requirements, Build, Installation
+=================================
 
 Requirements
 ------------
@@ -31,17 +31,16 @@ repository's root directory:
 
 The available options are the following:
 
-============================================== ===================================================================================================================================
-Name (Default)                                 Options
-============================================== ===================================================================================================================================
-PARALLELIZATION_HOST (:code:`CPP`)             :code:`CPP` = Serial Execution on Host/ :code:`OMP`/ :code:`TBB`  = Parallel Execution on Host with OpenMP or Intel's TBB
-PARALLELIZATION_DEVICE (:code:`CPP`)           :code:`CPP` = Serial Execution on Device/ :code:`OMP`/ :code:`TBB`  = Parallel Execution on Device with OpenMP or Intel's TBB
-LOGGING_LEVEL (:code:`2`)                      :code:`0` = TRACE/ :code:`1` = DEBUG/ :code:`2` = INFO / :code:`3` = WARN/ :code:`4` = ERROR/ :code:`5` = CRITICAL/ :code:`6` = OFF
-USE_LOCAL_TBB (:code:`OFF`)                    Use a local installation of :code:`TBB` instead of setting it up via :code:`CMake`
-BUILD_POLYHEDRAL_GRAVITY_DOCS (:code:`OFF`)    Build this documentation
-BUILD_POLYHEDRAL_GRAVITY_TESTS (:code:`ON`)    Build the Tests
-BUILD_POLYHEDRAL_PYTHON_INTERFACE (:code:`ON`) Build the Python interface
-============================================== ===================================================================================================================================
+================================================ ===================================================================================================================================
+Name (Default)                                   Options
+================================================ ===================================================================================================================================
+POLYHEDRAL_GRAVITY_PARALLELIZATION (:code:`CPP`) :code:`CPP` = Serial Execution / :code:`OMP` or :code:`TBB`  = Parallel Execution with OpenMP or Intel's TBB
+LOGGING_LEVEL (:code:`2`)                        :code:`0` = TRACE/ :code:`1` = DEBUG/ :code:`2` = INFO / :code:`3` = WARN/ :code:`4` = ERROR/ :code:`5` = CRITICAL/ :code:`6` = OFF
+USE_LOCAL_TBB (:code:`OFF`)                      Use a local installation of :code:`TBB` instead of setting it up via :code:`CMake`
+BUILD_POLYHEDRAL_GRAVITY_DOCS (:code:`OFF`)      Build this documentation
+BUILD_POLYHEDRAL_GRAVITY_TESTS (:code:`ON`)      Build the Tests
+BUILD_POLYHEDRAL_PYTHON_INTERFACE (:code:`ON`)   Build the Python interface
+================================================ ===================================================================================================================================
 
 Build & Installation with pip
 -----------------------------
@@ -59,6 +58,9 @@ at the :code:`setupy.py`.
 Installation with conda
 -----------------------
 
-TODO
+The python interface can be easily installed with `conda <https://anaconda.org/conda-forge/polyhedral-gravity-model>`__:
 
+.. code-block::
+
+    conda install -c conda-forge polyhedral-gravity-model