From 18a03da1a8c8f94ee5180eca63d3937ad94b52e8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?H=C3=A5kon=20H=C3=A6gland?= Date: Sun, 8 Dec 2024 22:31:31 +0100 Subject: [PATCH] Add doxygen comments Convert comment blocks into doxygen type comments --- opm/simulators/flow/ReservoirCoupling.hpp | 77 +++++++++++++++++------ 1 file changed, 57 insertions(+), 20 deletions(-) diff --git a/opm/simulators/flow/ReservoirCoupling.hpp b/opm/simulators/flow/ReservoirCoupling.hpp index 08ad81fa0..2308d4ce4 100644 --- a/opm/simulators/flow/ReservoirCoupling.hpp +++ b/opm/simulators/flow/ReservoirCoupling.hpp @@ -41,32 +41,69 @@ enum class MessageTag : int { void custom_error_handler_(MPI_Comm* comm, int* err, const std::string &msg); void setErrhandler(MPI_Comm comm, bool is_master); -// Utility class for comparing double values representing epoch dates (seconds since -// unix epoch) or elapsed time (seconds since the start of the simulation). -// NOTE: It is important that when comparing against start of a report step or similar, that -// that we do not miss these due to numerical issues. This is because communication between -// master and slave processes are based on these points in time. -// NOTE: Epoch values in this century (2000-2100) lies in the range of [1e9,4e9], and a double variable cannot -// represent such large values with high precision. For example, the date 01-01-2020 is equal -// to 1.5778368e9 seconds and adding 1e-7 seconds to this value will not change the value. -// So microseconds (1e-6) is approximately the smallest time unit we can represent for such a number. -// NOTE: Report steps seems to have a maximum resolution of whole seconds, see stepLength() in -// Schedule.cpp in opm-common, which returns the step length in seconds. +/// \brief Utility class for comparing double values representing epoch dates or elapsed time. +/// +/// This class is used to compare double values that represent: +/// - Epoch dates (seconds since the Unix epoch) +/// - Elapsed time (seconds since the start of the simulation) +/// +/// \note When comparing against the start of a report step or similar, it is important not to miss +/// these points due to numerical issues. Communication between master and slave processes is based +/// on these specific points in time. +/// +/// \note Epoch values in this century (2000-2100) fall within the range [1e9, 4e9]. A double variable +/// cannot represent such large values with high precision. For example, the date 01-01-2020 corresponds +/// to 1.5778368e9 seconds, and adding 1e-7 seconds to this value does not change it. Microseconds (1e-6) +/// are approximately the smallest time units that can be represented accurately for such numbers. +/// +/// \note Report steps appear to have a maximum resolution of whole seconds. See the `stepLength()` +/// function in `Schedule.cpp` in the `opm-common` module, which returns the step length in seconds. struct Seconds { + /// \brief Absolute tolerance used for comparisons. static constexpr double abstol = 1e-15; + + /// \brief Relative tolerance used for comparisons. static constexpr double reltol = 1e-15; - // We will will use the following expression to determine if two values a and b are equal: - // |a - b| <= tol = abstol + reltol * max(|a|, |b|) - // For example, assume abstol = reltol = 1e-15, then the following holds: - // - If |a| and |b| are below 1, then the absolute tolerance applies. - // - If a and b are above 1, then the relative tolerance applies. - // For example, for dates in the range 01-01-2000 to 01-01-2100, epoch values will be in the range - // [1e9, 4e9]. And we have 1e-15 * 1e9 = 1e-6, so numbers differing below one microsecond will - // be considered equal. - // NOTE: The above is not true for numbers close to zero, but we do not expect to compare such numbers. + + /// \brief Determines if two double values are equal within a specified tolerance. + /// + /// Two values \a a and \a b are considered equal if: + /// \f[ |a - b| \leq \text{tol} = \text{abstol} + \text{reltol} \times \max(|a|, |b|) \f] + /// + /// For example, if \a abstol = \a reltol = 1e-15: + /// - If \a |a| and \a |b| are below 1, the absolute tolerance applies. + /// - If \a a and \a b are above 1, the relative tolerance applies. + /// + /// \note For epoch dates between 01-01-2000 and 01-01-2100, epoch values are in the range [1e9, 4e9]. + /// Therefore, \f$ 10^{-15} \times 10^9 = 10^{-6} \f$, meaning differences smaller than one microsecond + /// will be considered equal. + /// + /// \note This approach is not accurate for numbers close to zero, but such comparisons are not expected. + /// + /// \param a First double value. + /// \param b Second double value. + /// \return True if \a a and \a b are considered equal within the tolerance. static bool compare_eq(double a, double b); + + /// \brief Determines if \a a is greater than \a b within the specified tolerance. + /// + /// \param a First double value. + /// \param b Second double value. + /// \return True if \a a is greater than \a b. static bool compare_gt(double a, double b); + + /// \brief Determines if \a a is greater than \a b within the specified tolerance. + /// + /// \param a First double value. + /// \param b Second double value. + /// \return True if \a a is greater than \a b. static bool compare_gt_or_eq(double a, double b); + + /// \brief Determines if \a a is less than or equal to \a b within the specified tolerance. + /// + /// \param a First double value. + /// \param b Second double value. + /// \return True if \a a is less than or equal to \a b. static bool compare_lt_or_eq(double a, double b); };