Line data Source code
1 0 : // Distributed under the MIT License.
2 : // See LICENSE.txt for details.
3 :
4 : #pragma once
5 :
6 : #include <cstddef>
7 : #include <iosfwd>
8 : #include <limits>
9 : #include <optional>
10 : #include <string>
11 :
12 : #include "NumericalAlgorithms/Convergence/Criteria.hpp"
13 : #include "NumericalAlgorithms/Convergence/Reason.hpp"
14 :
15 : /// \cond
16 : namespace PUP {
17 : class er;
18 : } // namespace PUP
19 : /// \endcond
20 :
21 : namespace Convergence {
22 :
23 : /*!
24 : * \brief Determine whether the `criteria` are met.
25 : *
26 : * \note This function assumes the `iteration_id` is that of the latest
27 : * completed step and that it is zero-indexed, where zero indicates the initial
28 : * state of the algorithm. Therefore, the `MaxIteration` criterion will match if
29 : * the `iteration_id` is equal or higher. For example, a `MaxIteration` of 0
30 : * means the algorithm should run no iterations, so it matches if the
31 : * `iteration_id` is 0 or higher since that's the initial state before any
32 : * steps have been performed. A `MaxIteration` of 1 matches if the
33 : * `iteration_id` is 1 or higher since one iteration is complete. At this point,
34 : * also the `residual_magnitude` reflects the state of the algorithm after
35 : * completion of the first iteration. The `initial_residual_magnitude` always
36 : * refers to the state before the first iteration has begun, i.e. where the
37 : * `iteration_id` is zero.
38 : *
39 : * \returns A `Convergence::Reason` if the criteria are met, or
40 : * `std::nullopt` otherwise. The possible convergence reasons are:
41 : *
42 : * - `Convergence::Reason::AbsoluteResidual` if the `residual_magnitude`
43 : * meets the convergence criteria's `absolute_residual`.
44 : * - `Convergence::Reason::RelativeResidual` if `residual_magnitude /
45 : * initial_residual_magnitude` meets the convergence criteria's
46 : * `relative_residual`.
47 : * - `Convergence::Reason::MaxIterations` if the `iteration_id` is the
48 : * convergence_criteria's `max_iterations` or higher. This is often
49 : * interpreted as an error because the algorithm did not converge in the
50 : * alloted number of iterations.
51 : */
52 1 : std::optional<Reason> criteria_match(const Criteria& criteria,
53 : size_t iteration_id,
54 : double residual_magnitude,
55 : double initial_residual_magnitude);
56 :
57 : /*!
58 : * \brief Signals convergence or termination of the algorithm.
59 : *
60 : * \details Evaluates to `true` if the algorithm has converged or terminated and
61 : * no further iterations should be performed. In this case, the `reason()`
62 : * member function provides more information. If `false`, calling `reason()` is
63 : * an error.
64 : *
65 : * The stream operator provides a human-readable description of the convergence
66 : * status.
67 : *
68 : * This type default-constructs to a state that signals the algorithm has
69 : * not yet converged.
70 : */
71 1 : struct HasConverged {
72 : public:
73 0 : HasConverged() = default;
74 : /*!
75 : * \brief Determine whether the \p criteria are met by means of
76 : * `Convergence::criteria_match`.
77 : */
78 1 : HasConverged(const Criteria& criteria, size_t iteration_id,
79 : double residual_magnitude, double initial_residual_magnitude);
80 :
81 : /// Construct at a state where `iteration_id` iterations of a total of
82 : /// `num_iterations` have completed. Use when the algorithm is intended to run
83 : /// for a fixed number of iterations. The convergence `reason()` will be
84 : /// `Convergence::Reason::NumIterations`.
85 1 : HasConverged(size_t num_iterations, size_t iteration_id);
86 :
87 : /*!
88 : * \brief Construct a state manually.
89 : *
90 : * Currently only allows to construct a state with `Reason::Error`. Use the
91 : * other constructors for the other `Reason`s.
92 : */
93 1 : HasConverged(Reason reason, std::optional<std::string> error_message,
94 : size_t iteration_id);
95 :
96 0 : explicit operator bool() const { return static_cast<bool>(reason_); }
97 :
98 : /*!
99 : * \brief The reason the algorithm has converged.
100 : *
101 : * \warning Calling this function is an error if the algorithm has not yet
102 : * converged.
103 : */
104 1 : Reason reason() const;
105 :
106 : /*!
107 : * \brief Error message if reason is `Reason::Error`
108 : *
109 : * \warning You may only call this function if the `reason()` is
110 : * `Reason::Error`.
111 : */
112 1 : const std::string& error_message() const;
113 :
114 : /// The number of iterations the algorithm has completed
115 1 : size_t num_iterations() const;
116 :
117 : /// The residual magnitude after the last iteration. NaN if no iteration has
118 : /// completed yet.
119 1 : double residual_magnitude() const;
120 :
121 : /// The residual magnitude before the first iteration. NaN if this information
122 : /// is not available yet.
123 1 : double initial_residual_magnitude() const;
124 :
125 : /// Throw an exception if the `reason()` is `Reason::Error`.
126 1 : void check_for_error() const;
127 :
128 : // NOLINTNEXTLINE(google-runtime-references)
129 0 : void pup(PUP::er& p);
130 :
131 0 : friend bool operator==(const HasConverged& lhs, const HasConverged& rhs);
132 0 : friend bool operator!=(const HasConverged& lhs, const HasConverged& rhs);
133 :
134 0 : friend std::ostream& operator<<(std::ostream& os,
135 : const HasConverged& has_converged);
136 :
137 : private:
138 0 : std::optional<Reason> reason_{};
139 0 : std::optional<std::string> error_message_ = std::nullopt;
140 0 : Criteria criteria_{};
141 0 : size_t iteration_id_{};
142 0 : double residual_magnitude_ = std::numeric_limits<double>::quiet_NaN();
143 0 : double initial_residual_magnitude_ = std::numeric_limits<double>::quiet_NaN();
144 : };
145 :
146 : } // namespace Convergence
|
