Skip to content

Commit

Permalink
state mesh checking to README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
schuhmaj committed Mar 25, 2024
1 parent be06023 commit c497c61
Showing 3 changed files with 23 additions and 1 deletion.
16 changes: 16 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
@@ -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
6 changes: 6 additions & 0 deletions docs/api/python.rst
Original file line number Diff line number Diff line change
@@ -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)`.

2 changes: 1 addition & 1 deletion docs/quick_start_python.rst
Original file line number Diff line number Diff line change
@@ -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:

0 comments on commit c497c61

Please sign in to comment.