Update code documentation & Bump version number

Improved the code comments for better clarity and updated some of the examples in the docs. Also corrected minor typos in documentation and comments. The package version number is updated to 3.1.

docs/api/util.rst

@@ -6,7 +6,7 @@ Overview
 
 The namespace :code:`polyhedralGravity::util` contains utility
 for operations on iterable Containers, Constants and syntactic
-sugar for using the thrird party dependency :code:`thrust`.
+sugar for using the third party dependency :code:`thrust`.
 
 Documentation
 -------------

docs/quickstart/examples_cpp.rst

@@ -79,7 +79,7 @@ and we check the if the plane unit normals are actually outwards pointing
 
         // Returns either a single of vector of results
         // Here, we only have one point. Thus we get a single result
-        Polyhedron polyhedron{vertices, faces, density, PolyhedronIntegrity::VERIFY};
+        Polyhedron polyhedron{vertices, faces, density, NormalOrientation::OUTWARDS, PolyhedronIntegrity::VERIFY};
         const auto[pot, acc, tensor] = GravityModel::evaluate(polyhedron, point, false);
 
 
@@ -131,12 +131,12 @@ The result will always be fine.
 
         // Reading the configuration from a yaml file
         std::shared_ptr<ConfigSource> config = std::make_shared<YAMLConfigReader>("config.yaml");
-        Polyhedron poly = config->getDataSource()->getPolyhedron();
+        auto polyhedralSource = config->getDataSource()->getPolyhedralSource();
         double density = config->getDensity();
         std::array<double, 3> point = config->getPointsOfInterest()[0];
 
-        Polyhedron polyhedron{files, density, NormalOrientation::OUTWARDS, PolyhedronIntegrity::HEAL};
-        GravityResult result = GravityModel::evaluate(poly, density, point);
+        Polyhedron polyhedron{polyhedralSource, density, NormalOrientation::OUTWARDS, PolyhedronIntegrity::HEAL};
+        const auto[pot, acc, tensor] = GravityModel::evaluate(polyhedron, point);
 
 
 GravityEvaluable (with caching)

setup.py

@@ -175,7 +175,7 @@ def build_extension(self, ext):
 # --------------------------------------------------------------------------------
 setup(
     name="polyhedral_gravity",
-    version="3.0",
+    version="3.1",
     author="Jonas Schuhmacher",
     author_email="[email protected]",
     description="Package to compute full gravity tensor of a given constant density polyhedron for arbitrary points "

src/polyhedralGravity/model/Polyhedron.h

@@ -151,7 +151,7 @@ namespace polyhedralGravity {
          *
          * @note ASSERTS PRE-CONDITION that the in the indexing in the faces vector starts with zero!
          * @throws std::invalid_argument if no face contains the node zero indicating mathematical index
-         * @throws std::invalid_argument dpending on the {@param integrity} flag
+         * @throws std::invalid_argument dpending on the {@link integrity} flag
          */
         Polyhedron(
                 const std::vector<Array3> &vertices,
@@ -170,7 +170,7 @@ namespace polyhedralGravity {
          *
          * @note ASSERTS PRE-CONDITION that the in the indexing in the faces vector starts with zero!
          * @throws std::invalid_argument if no face contains the node zero indicating mathematical index
-         * @throws std::invalid_argument dpending on the {@param integrity} flag
+         * @throws std::invalid_argument dpending on the {@link integrity} flag
          */
         Polyhedron(
                 const PolyhedralSource &polyhedralSource,
@@ -188,7 +188,7 @@ namespace polyhedralGravity {
          *
          * @note ASSERTS PRE-CONDITION that the in the indexing in the faces vector starts with zero!
          * @throws std::invalid_argument if no face contains the node zero indicating mathematical index
-         * @throws std::invalid_argument dpending on the {@param integrity} flag
+         * @throws std::invalid_argument dpending on the {@link integrity} flag
          */
         Polyhedron(const PolyhedralFiles &polyhedralFiles, double density,
                    const NormalOrientation &orientation = NormalOrientation::OUTWARDS,
@@ -204,7 +204,7 @@ namespace polyhedralGravity {
          *
          * @note ASSERTS PRE-CONDITION that the in the indexing in the faces vector starts with zero!
          * @throws std::invalid_argument if no face contains the node zero indicating mathematical index
-         * @throws std::invalid_argument dpending on the {@param integrity} flag
+         * @throws std::invalid_argument dpending on the {@link integrity} flag
          */
         Polyhedron(const std::variant<PolyhedralSource, PolyhedralFiles> &polyhedralSource, double density,
                    const NormalOrientation &orientation = NormalOrientation::OUTWARDS,

src/polyhedralGravity/util/UtilityFloatArithmetic.h

@@ -18,7 +18,7 @@ namespace polyhedralGravity::util {
     /**
      * This relative EPSILON is utilized ONLY for testing purposes to compare intermediate values to
      * Tsoulis' reference implementation Fortran.
-     * It is used in the {@ref polyhedralGravity::util::almostEqualRelative} function.
+     * It is used in the {@link polyhedralGravity::util::almostEqualRelative} function.
      *
      * @note While in theory no difference at all is observed when compiling this program on Linux using GCC on x86_64,
      *  the intermediate values change when the program is compiled in different environments.
@@ -28,7 +28,7 @@ namespace polyhedralGravity::util {
 
     /**
      * The maximal allowed ULP distance utilized for FloatingPoint comparisons using the
-     * {@ref polyhedralGravity::util::almostEqualUlps} function.
+     * {@link polyhedralGravity::util::almostEqualUlps} function.
      *
      * @see https://randomascii.wordpress.com/2012/02/25/comparing-floating-point-numbers-2012-edition/
      */
@@ -42,7 +42,7 @@ namespace polyhedralGravity::util {
      * @param lhs The left hand side floating point number to compare.
      * @param rhs The right hand side floating point number to compare.
      * @param ulpDistance The maximum acceptable ULP distance between the two floating points
-     *      for which they would be considered near each other. This is optional and by default, it will be MAX_ULP_DISTANCE.
+     *      for which they would be considered near each other. This is optional and by default, it will be {@link MAX_ULP_DISTANCE}.
      *
      * @return true if the ULP distance between lhs and rhs is less than or equal to the provided ulpDistance value, otherwise, false.
      *  Returns true if both numbers are exactly the same. Returns false if the signs do not match.
@@ -60,7 +60,7 @@ namespace polyhedralGravity::util {
      * @param lhs The first floating-point number to be compared.
      * @param rhs The second floating-point number to be compared.
      * @param epsilon The tolerance for comparison. Two numbers that are less than epsilon apart are considered equal.
-     *                The default value is `EPSILON`.
+     *                The default value is {@link EPSILON_ALMOST_EQUAL}.
      *
      * @return boolean value - Returns `true` if the absolute difference between `lhs` and `rhs` is less than or equal to
      *                         the relative error factored by the larger of the magnitude of `lhs` and `rhs`. Otherwise, `false`.

src/polyhedralGravityPython/PolyhedralGravityPython.cpp

@@ -152,8 +152,8 @@ PYBIND11_MODULE(polyhedral_gravity, m) {
 
                                         * :code:`AUTOMATIC` (Default): Prints to stdout and throws ValueError if normal_orientation is wrong/ inconsisten
                                         * :code:`VERIFY`: Like :code:`AUTOMATIC`, but does not print to stdout
-                                        * :code:`DISABLE`: Recommened, when you know the mesh to avoid to pay :math:`O(n^2)` runtime. Disables ALL checks
-                                        * :code`HEAL`: Automatically fixes the normal_orientation and vertex ordering to the correct values
+                                        * :code:`DISABLE`: Recommened, when you are familiar with the mesh to avoid :math:`O(n^2)` runtime cost. Disables ALL checks
+                                        * :code:`HEAL`: Automatically fixes the normal_orientation and vertex ordering to the correct values
 
             Raises:
                 ValueError: If the faces array does not contain a reference to vertex 0 indicating an index start at 1
@@ -182,7 +182,7 @@ PYBIND11_MODULE(polyhedral_gravity, m) {
                 This utility is mainly for diagnostics and debugging purposes. If the polyhedron is constrcuted with `integrity_check`
                 set to :code:`AUTOMATIC` or :code:`VERIFY`, the construction fails anyways.
                 If set to :code:`HEAL`, this method should return an empty set (but maybe a different ordering than initially specified)
-                Only if set to code:`DISABLE`, then this method might actually return a set with faulty indices.
+                Only if set to :code:`DISABLE`, then this method might actually return a set with faulty indices.
                 Hence, if you want to know your mesh error. Construct the polyhedron with :code:`integrity_check=DISABLE` and call this method.
             )mydelimiter")
             .def("__getitem__", &Polyhedron::getResolvedFace, R"mydelimiter(