From f1f26d7bcc7adb77dcedc35d4dc53171413957a2 Mon Sep 17 00:00:00 2001 From: Jonas Schuhmacher Date: Tue, 7 May 2024 21:45:53 +0200 Subject: [PATCH] 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 | 2 +- docs/quickstart/examples_cpp.rst | 8 ++++---- setup.py | 2 +- src/polyhedralGravity/model/Polyhedron.h | 8 ++++---- src/polyhedralGravity/util/UtilityFloatArithmetic.h | 8 ++++---- src/polyhedralGravityPython/PolyhedralGravityPython.cpp | 6 +++--- 6 files changed, 17 insertions(+), 17 deletions(-) diff --git a/docs/api/util.rst b/docs/api/util.rst index 4c85418..9dc761b 100644 --- a/docs/api/util.rst +++ b/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 ------------- diff --git a/docs/quickstart/examples_cpp.rst b/docs/quickstart/examples_cpp.rst index 40b9135..7cc49fc 100644 --- a/docs/quickstart/examples_cpp.rst +++ b/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 config = std::make_shared("config.yaml"); - Polyhedron poly = config->getDataSource()->getPolyhedron(); + auto polyhedralSource = config->getDataSource()->getPolyhedralSource(); double density = config->getDensity(); std::array 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) diff --git a/setup.py b/setup.py index aaa5f30..70d486d 100644 --- a/setup.py +++ b/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="jonas.schuhmacher@tum.de", description="Package to compute full gravity tensor of a given constant density polyhedron for arbitrary points " diff --git a/src/polyhedralGravity/model/Polyhedron.h b/src/polyhedralGravity/model/Polyhedron.h index cc4a461..ef74b7a 100644 --- a/src/polyhedralGravity/model/Polyhedron.h +++ b/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 &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, double density, const NormalOrientation &orientation = NormalOrientation::OUTWARDS, diff --git a/src/polyhedralGravity/util/UtilityFloatArithmetic.h b/src/polyhedralGravity/util/UtilityFloatArithmetic.h index 8a9f995..60507c7 100644 --- a/src/polyhedralGravity/util/UtilityFloatArithmetic.h +++ b/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`. diff --git a/src/polyhedralGravityPython/PolyhedralGravityPython.cpp b/src/polyhedralGravityPython/PolyhedralGravityPython.cpp index 75a785c..e6f4d79 100644 --- a/src/polyhedralGravityPython/PolyhedralGravityPython.cpp +++ b/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(