From c497c61049f1e2d3403493e0c900c2a28d255f6b Mon Sep 17 00:00:00 2001
From: Jonas Schuhmacher <jonas.schuhmacher@tum.de>
Date: Mon, 25 Mar 2024 21:01:43 +0100
Subject: [PATCH] state mesh checking to README.md

---
 README.md                   | 16 ++++++++++++++++
 docs/api/python.rst         |  6 ++++++
 docs/quick_start_python.rst |  2 +-
 3 files changed, 23 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 61003a4..b6e6707 100644
--- a/README.md
+++ b/README.md
@@ -70,6 +70,7 @@ the python interface.
 
 The [GitHub Pages](https://esa.github.io/polyhedral-gravity-model) of this project
 contain the full extensive documentation.
+It also covers the content of the `polyhedral_gravity.utility` module to check the mesh sanity.
 
 ### Minimal Python Example
 
@@ -81,6 +82,7 @@ import numpy as np
 import polyhedral_gravity
 
 # We define the cube as a polyhedron with 8 vertices and 12 triangular faces
+# The polyhedron's (here: cube) normals need to point outwards (see below for checking this)
 # The density is set to 1.0
 cube_vertices = np.array(
     [[-1, -1, -1], [1, -1, -1], [1, 1, -1], [-1, 1, -1],
@@ -125,6 +127,17 @@ Note that the `computation_point` could also be (N, 3)-shaped array.
 In this case, the return value of `evaluate(..)` or an `GravityEvaluable` will
 be a list of triplets comprising potential, acceleration, and tensor.
 
+The gravity model requires that the polyhedron's plane unit normals point outwards
+the polyhedron. In case you are unsure, you can check for this property by using the `utility` module beforehand.
+The method also verifies that all triangles are actually triangles with a non-zero
+surface area.
+
+```python
+print("Valid Mesh?", polyhedral_gravity.utility.check_mesh(cube_vertices, cube_faces))
+```
+
+If the method returns `False`, then you need to revise the vertex-ordering.
+
 ### Minimal C++ Example
 
 The following example shows how to use the C++ library to compute the gravity.
@@ -161,6 +174,9 @@ const auto[potential, acceleration, tensor] = evaluable(point, parallel);
 const auto results = evaluable(points);
 ```
 
+Similarly to Python, the C++ implementation also provides mesh checking capabilities.
+For reference, have a look at [the main method](./src/main.cpp).
+
 ## Installation
 
 ### With conda
diff --git a/docs/api/python.rst b/docs/api/python.rst
index 289f44a..30956d7 100644
--- a/docs/api/python.rst
+++ b/docs/api/python.rst
@@ -102,6 +102,9 @@ like it is required by the polyhedral-gravity model.
     :return: True if no triangle is degenerate and the polyhedron's plane unit normals are all pointing outwards.
     :rtype: Bool
 
+    .. note::
+        This method has quadratic runtime complexity :math:`O(n^2)`
+
 .. py:function:: check_mesh(input_files)
     :noindex:
 
@@ -115,3 +118,6 @@ like it is required by the polyhedral-gravity model.
     :return: True if no triangle is degenerate and the polyhedron's plane unit normals are all pointing outwards.
     :rtype: Bool
 
+    .. note::
+        This method has quadratic runtime complexity :math:`O(n^2)`.
+
diff --git a/docs/quick_start_python.rst b/docs/quick_start_python.rst
index 6f80581..337fc33 100644
--- a/docs/quick_start_python.rst
+++ b/docs/quick_start_python.rst
@@ -3,7 +3,7 @@ Quick Start Python
 
 The use of the Python interface is pretty straight-forward since
 there is only one method: :code:`evaluate(..)` or the alternative
-class :code:`GravityEvaluable` caching the polyhedron data.
+class :code:`GravityEvaluable` caching the polyhedron.
 
 The method calls follow the same pattern as the C++ interface. Thus it is always: